@usvc/component-tracer NPM

`@usvc/component-tracer`

Distributed trace management package using Zipkin for use in an Express application.

Scope

Creation of a tracer
Allow for configuration of sample rate
Allow for configuration of headers sent to Zipkin service
Allow for configuration of Zipkin service URL
Allow for configuration of trace ID bit count

Installation

npm i @usvc/component-tracer;
# OR
yarn add @usvc/component-tracer;

Usage

// es5
const {
  createTracer,
  getContextProviderMiddleware,
} = require('@usvc/component-tracer');

// es6
import {
  createTracer,
  getContextProviderMiddleware,
} from '@usvc/component-tracer';

Basic

const express = require('express');
// require module as per ^
const tracer = createTracer();
const app = express();
app.use(tracer.getExpressMiddleware());
// ...

Full Configuration

const express = require('express');
// require module as per ^
const tracer = createTracer({
  sampleRate: 1,
  headers: {},
  httpTimeout: 5.0,
  url: 'http://localhost:9411',
  traceId128bit: true,
});
const app = express();
app.use(tracer.getExpressMiddleware());
// ...

API Documentaiton

`createTracer(:options)`

Creates the tracer object. The :options parameter has the following schema:

Key	Type	Defaults To	Description
`sampleRate`	Number	`1`	The frequency of which to sample requests - 1 means sample everything, 0 means sample nothing
`headers`	Object	`{}`	Additional headers to be sent to the Zipkin service - use this to add stuff like `X-Authorization` headers
`httpTimeout`	Number	`5.0`	Timeout in seconds for a call to the Zipkin service
`url`	URL	`http://localhost:9411`	The base URL of your Zipkin service
`traceId128Bit`	Boolean	`true`	Enables 128-bit length trace IDs

The returned object has the following methods:

Method	Description
`getContext()`	Retrieves the internally created context
`getExpressMiddleware()`	Retrieves an array of middlewares usable via `express().use(...)`
`getTracer()`	Retrieves the raw Zipkin tracer

`getContextProviderMiddleware(:options)`

Returns an Express middleware that adds a .context property to the Express Request object and passes it downstream. The :options has the following schema:

Key	Type	Defaults To	Description
`context`	`Context<T>`	`undefined`	The context object retrievable via the `.getContext()` method of the object returned by `createTracer()`. Alternatively, can used alone.