❀Network Powering Makers


    1.4.3Β β€’Β PublicΒ β€’Β Published

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

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

    Overview | Usage | Api

    Contributors License type language test style


    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.


    npm install @uswitch/koa-tracer
    import Koa from 'koa'
    import tracer, { eventTrace, eventError } from '@uswitch/koa-tracer'
    const app = new Koa()
    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.


    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



    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 */


    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'


    Thanks goes to these wonderful people (emoji key):

    Dom Charlesworth

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

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




    npm i @uswitch/koa-tracer

    DownloadsWeekly Downloads






    Unpacked Size

    331 kB

    Total Files


    Last publish


    • phelm
    • ricardomccerqueira
    • domtronn
    • riksanchez
    • uswitch-publisher
    • brendonboshell
    • velrok
    • daniel.whyte
    • peterhorne-uswitch
    • salomao-rodrigues
    • enio
    • segger87
    • joshuacroad
    • jonthanfielding
    • floraharvey
    • kristink
    • giorgia-amici
    • barneyfoxuk
    • nate25
    • natyeo
    • mferry2016
    • daffydowden