@uswitch/koa-tracer

    1.5.0Β β€’Β PublicΒ β€’Β Published

    πŸ•΅οΈβ€β™€οΈ Koa Tracer

    A Koa middleware for tracing your request's lifecycle, efficiently & effectively.

    Overview | Usage | Api

    Contributors License type language test style

    Overview

    This package is a Koa middleware to allow tracing the lifecycle of requests.

    It tries to implement the following features;

    • πŸ“š Namespaced traces - Group messages by namespace
    • ⏱ Namespaced relative time diffs - Display the time difference in ms between events in a namespace.
    • 🌍 Global relative time diffs - Display time difference between request start and the trace event.
    • πŸ› Decoupled errors - Log errors separately to handling them.
    • πŸ† Per-request trace - Be able to reference all traces back to a single request!

    All of this is designed to make it easy to rebuild an exact picture of what's happening in your code.


    Usage

    npm install @uswitch/koa-tracer
    import Koa from 'koa'
    import tracer, { eventTrace, eventError } from '@uswitch/koa-tracer'
    
    const app = new Koa()
    
    app.use(tracer())
    
    app.on('koa-tracer:trace', Logger.log)
    app.on('koa-tracer:error', Logger.err)
    
    app.on(eventTrace, Logger.log)
    app.on(eventError, Logger.err)

    This package uses Event Emitters to decouple the handling of runtime tracing and logging. This means that you can decide how you want to handle traces and errors separately with the koa-tracer:trace & koa-tracer:error events.

    However, all traces and errors are available in Koa's context at the end of the request to be used in access logs, or whatever else you might want.

    Functions

    trace - fn (ctx, &optional namespace, message)
    • ctx [Object] - the Koa ctx object
    • namespace [String] - A namespace for the trace message (optional)
    • message [String/Object] - The details of the trace message
    traceError - fn (ctx, err)
    • ctx [Object] - the Koa ctx object
    • err [String/Object/Error] - The details of the error

    API

    Objects

    A trace object looks like this;

    {
      "time": "Date"       // Date for when that trace was logged
      "timeDiff": 12       // Diff in `ms` between this and the first trace in namspace
      "initDiff": 30       // Diff in `ms` between this and start of request
      "msg": "Foo bar"     // The message passed into the trace
      [other properties]   // Any other properties passed in
    }

    An error object looks like this;

    {
      "time": "Date"       // Date for when that error was logged
      "msg": "Foo bar"     // The message passed into the error
      [other properties]   // Any other properties passed in
    }

    The state object, after a request, looks like this;

    {
      "traceStart": "Date" /* Date when the request started */
      "trace": {
        "__general": { 
          traces: [ /* List of traces without namespace */ ],
          tracesLength: 50,
          timeDiff: 12,
          initDiff: 12
        },
        "namespace": { 
          traces: [ /* List of traces in `namespace` */ ],
          tracesLength: 50,
          timeDiff: 12,
          initDiff: 12
        }
      }
    
      "errorsCount": 12  /* The number of errors occured in this request */
      "errors": [
        /* List of errors */
      ]
    }

    Events

    The following events are fired on trace and error logging completion.

    • koa-tracer:trace => ({ ctx, key, trace })
    • koa-tracer:error => ({ ctx, error, original })

    N.B. These events are called with Objects

    They can be imported from the koa-tracer module, as

    import { eventTrace, eventError } from 'koa-tracer'

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Dom Charlesworth

    πŸ’» πŸ“– πŸ€” πŸ”Œ

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Keywords

    none

    Install

    npm i @uswitch/koa-tracer

    DownloadsWeekly Downloads

    1,176

    Version

    1.5.0

    License

    MIT

    Unpacked Size

    331 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar