@uswitch/koa-tracer

🕵️‍♀️ Koa Tracer

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

Overview | Usage | Api

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!