koa-trace

Koa Trace

A generic tracing module. Use .trace() calls in your middleware and send all the data to your favorite tracer or stats aggregator like jstrace, dtrace, ktap, statds, etc. debug also supported!

app.use(async function (ctx, next) {
  // give each request some sort of ID
  ctx.id = crypto.randomBytes(12)

  // log events with optional arguments
  ctx.trace('start')
  await next()
  ctx.trace('finish')
})

Enable debug usage:

app.debug()

Now run your app with DEBUG=koa-trace:* and watch the events unfold:

You can see the debug statements grouped by request ID. Then the event is shown, the time difference since the last statement, and the arguments passed to .trace().

Background

I want to add something like this to Koa, but we're not sure what the best way possible is. Please provide feedback on this module, including suggestions or criticisms. I'm sure the debug usage could use a lot of work.

Convention

There are no conventions as to how to name your events or what arguments to trace. The only thing you should do is create some sort of this.id, either a Buffer or a String, before you do any .trace() calls. You will need this anyway in your logs.

This module is backend agnostic. There is no possible way to support all the features of all the different backends. If you want to use backend specific stuff, you might as well use a module specific to it!

If you want to create a convention, let me know! We can start a doc or wiki or something.

API

require('koa-trace')(app)

Add the instrumentation methods to app.

const Koa = require('koa')
const app = new Koa()
require('koa-trace')(app)

this.trace(event, args...)

Emit an event with optional arguments.

app.use(async function (ctx, next) {
  ctx.trace('something', 1, 2, 3)
  await next()
})

app.instrument(function (context, event, date, args) {})

Listen to all the trace calls.

• context is the koa this context.
• event is the traced event.
• date is a Date instance of when the trace was called. This means that you don't have to trace any of your own Dates.
• args is an array of all the arguments passed.

Any backends will need to use this method to hook into the trace calls.

app.debug()

Enable all the debug logging. This is not enabled by default, so you might want to do something like:

if (process.env.NODE_ENV !== 'production') app.debug()

To view all the debug logs, run the node process with DEBUG=koa-trace:*.