Aims to provide standard middleware and instrumentation tooling for metrics in Koa

Usage no npm install needed!

<script type="module">
  import shopifyKoaMetrics from 'https://cdn.skypack.dev/@shopify/koa-metrics';



Build Status Build Status License: MIT npm version

Opinionated performance metric tracking for Koa, implemented with DogStatsD.


$ yarn add @shopify/koa-metrics


import Koa from 'koa';
import metrics from '@shopify/koa-metrics';

const app = new Koa();

    prefix: 'AppName',
    host: 'some-statsd-host.com:8125',


The passed in options object adheres to the following API:

prefix (required)

The global StatsD metric name prefix; should be provided in PascalCase.

host (required)

The url for the StatsD host; should be provided in the format: hostname:port.


An instance of the Metrics object will be available on ctx.metrics further down in the middleware stack.


.distribution(name: string, value: number, sampleRate?: number, tags?: Tags)

Sends a distribution command with the specified value in milliseconds.

.initTimer(): Timer

Returns a new Timer started at the current process.hrtime()


.stop(): number

Returns the time, in milliseconds, since the Timer was created.


tags are an object keyed by the name of the corresponding tag. For example:

  name: value,
  name2: value2

Intelligent Defaults

The global metric name prefix is provided through the options object.

This package automatically provides performance metrics for HTTP requests.

Standard tags

  • path
  • request_method
  • response_code
  • response_type (eg. 2xx, 3xx, ...)

Default Metrics


Time to complete a request, from the application perspective.


Time before a request actually started being processed.

This metric is emitted when the application start processing a request. It relies on the presence of a header X-Request-Start set by the first HTTP hop.


This metric is based on the response header Content-Length. Some responses don't provide this header (chunked encoding); in those cases, this will not be reported.