Overview

This package is a Koa library to do a lot of the heavy lifting to enable zipkin tracing around your service and of upstream requests within your app.

It tries to encapsulate some of the run time mentality of how you build a service with the compile time integration of `zipkin.js** libraries and instrumentations.

N.B. - This library is opinionated. It provides;

• Instrumentation for fetch
• A HTTP / Client side logger designed to work with @uswitch/koa-signal

Usage

Using a fetch client without a cache

This is the simplest way to get zipkin tracing working with a koa application and sending to a Zipkin server.

// Define a module `zipkin.js`

import { middleware, fetch, Logger, Tracer } from '@uswitch/koa-zipkin'
import fetch from 'node-fetch'

const { middleware, fetch, Logger, Tracer } = koaZipkin
const { NODE_ENV, ZIPKIN_HOST, APP_NAME = 'example-service' } = process.env

const logger = Logger({ local: NODE_ENV === 'development', endpoint: ZIPKIN_HOST })
const tracer = Tracer(APP_NAME, logger)

export const zipkin = middleware({ tracer })
export const zipkinFetch = fetch({ local: APP_NAME, client: fetch, tracer })

// ----------------------------------------
// Then in your `koa` server you can just use
import { zipkin, zipkinFetch } from './zipkin'

app.use(zipkin)

app.use((ctx, next) => zipkinFetch({ remote: 'my-upstream' }, 'http://my-upstream'))

Using axios with a cache

Similarly to above, there are some benefits to using axios with its cache adapter. You get added logging of cache hits and misses as well as the zipkin tracing. However, this needs a few extra bits like adding the X-Cache-Enabled:true header to your responses.

// Define a module `zipkin.js`
import koaZipkin from '@uswitch/koa-zipkin'

import axios from 'axios'
import cache from 'axios-cache-adapter'

const { middleware, fetch, Logger, Tracer } = koaZipkin
const { USE_CACHE = true, NODE_ENV, APP_NAME = 'example-uf-service' } = process.env

const { adapter } = cache.setupCache({ maxAge: USE_CACHE ? 10 * 1000 : 0 })
const client = axios.create({ adapter })

/* Mark the intent of using a cache */
client.interceptors.response.use(
  (res) => {
    res.headers['X-Cache-Enabled'] = true
    return res
  },
  Promise.reject
)

const tracer = Tracer(APP_NAME, Logger({ local: NODE_ENV === 'development' }))

export const zipkin = middleware({ tracer })
export const zipkinFetch = fetch({ local: APP_NAME, client, tracer })

Enabling experimental ContextCLS feature to support tracing through code with promises / async / await

Please see https://github.com/openzipkin/zipkin-js/tree/master/packages/zipkin-context-cls#a-note-on-cls-context-and-promises, and note that by default - asynchronous code is not supported by ContextCLS. If you see fetches appearing in Zipkin with a different Trace ID, this could be the reason..

To enable asynchronous ContextCLS, create the Tracer object as follows:

const tracer = Tracer(APP_NAME, logger, true)

Please also note there are known performance implications of enabling this feature on Node versions below 16.3.0