koajs / trace

generic tracing for koa

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:*.

trace's Issues

Support koa 2

In koajs/koala#17, I tried to get koa-trace working with koa 2, and I can't seem to swing it. I get an error where context is not defined when the trace is ended, at the tail end of the request. I think there may be some work to do to support koa 2, but I haven't done enough digging to know what that is just yet.

Wrap functions on context object.

It'd be neat if there was a pattern to register functions on the context object to expose them, and conditionally include tracing.

app.use(function* (next) {
  this.tracing = Math.random() > 0.5
  this.register('render', render)
  yield* next
})

app.use(function* (next) {
  // The call to `this.render(...)` will automatically include calls for
  // `this.trace('render entry')` and `this.trace('render exit')`
  this.body = this.render('template', { foo: 'bar' })
})

Resolve npm audit issues

i-200077 foss/trace ‹master*› » npm audit

                       === npm audit security report ===

# Run  npm install --save-dev [email protected]  to resolve 4 vulnerabilities
SEMVER WARNING: Recommended action is a potentially breaking change
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low           │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ debug                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ mocha [dev]                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ mocha > debug                                                │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/534                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Moderate      │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ ms                                                           │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ mocha [dev]                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ mocha > debug > ms                                           │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/46                        │
└───────────────┴──────────────────────────────────────────────────────────────┘


┌───────────────┬──────────────────────────────────────────────────────────────┐
│ High          │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ minimatch                                                    │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ mocha [dev]                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ mocha > glob > minimatch                                     │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/118                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Critical      │ Command Injection                                            │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ growl                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ mocha [dev]                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ mocha > growl                                                │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/146                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


# Run  npm install [email protected]  to resolve 2 vulnerabilities
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low           │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ debug                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ koa                                                          │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ koa > debug                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/534                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


┌───────────────┬──────────────────────────────────────────────────────────────┐
│ High          │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ fresh                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ koa [dev]                                                    │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ koa > fresh                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/526                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


# Run  npm install [email protected]  to resolve 1 vulnerability
SEMVER WARNING: Recommended action is a potentially breaking change
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low           │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ debug                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ debug                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ debug                                                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/534                       │
└───────────────┴──────────────────────────────────────────────────────────────┘


found 7 vulnerabilities (3 low, 1 moderate, 2 high, 1 critical) in 77 scanned packages
  run `npm audit fix` to fix 2 of them.
  5 vulnerabilities require semver-major dependency updates.