https://github.com/koajs/trace

generic tracing for koa
https://github.com/koajs/trace

Last synced: 2 months ago
JSON representation

generic tracing for koa

• Host: GitHub
• URL: https://github.com/koajs/trace
• Owner: koajs
• License: mit
• Created: 2014-06-19T07:34:26.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2018-12-11T13:07:09.000Z (about 6 years ago)
• Last Synced: 2024-04-14T13:08:40.877Z (8 months ago)
• Language: JavaScript
• Size: 303 KB
• Stars: 53
• Watchers: 6
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-koa - trace - generic tracing for koa (Middleware)

README

        

# 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](http://github.com/visionmedia/debug) also supported!

```js

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](http://github.com/visionmedia/debug) usage:

```js

app.debug()

```

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

![debug statements](assets/debug.png)

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](http://github.com/visionmedia/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`.

```js

const Koa = require('koa')

const app = new Koa()

require('koa-trace')(app)

```

### this.trace(event, args...)

Emit an `event` with optional arguments.

```js

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 `Date`s.

- `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:

```js

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

```

To view all the debug logs,

run the node process with `DEBUG=koa-trace:*`.