@usvc/tracer

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

Scope

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

Installation

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

Usage

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

// es6
import {
  createTracer,
  getContextProviderMiddleware,
} from '@usvc/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. |

Examples

WIP

Development

WIP

License

This package is licensed under the MIT license.

View the license at LICENSE.

Changelog

0.1.x

0.1.0

• Initial release

Contributors

| Name | Email | Website | About Me | | --- | --- | --- | --- | | zephinzer | - | https://github.com/zephinzer | - |

Cheers