Quick Start

Example

The package contains a example using a naive MockTracer implementation. To run the example:

npm run example

The output should look something like:

Spans:

parent_span - 1521ms

tag 'custom':'tag value'

tag 'alpha':'1000'

child_span - 503ms

tag 'alpha':'200'

tag 'beta':'50'

Code snippet

In your JavaScript code, add instrumentation to the operations to be tracked. This is composed primarily of using "spans" around operations of interest and adding log statements to capture useful data relevant to those operations.

consthttp=require('http');

constopentracing=require('opentracing');

// NOTE: the default OpenTracing tracer does not record any tracing information.

As noted in the source snippet, the default behavior of the opentracing package is to act as a "no op" implementation. To capture and make the tracing data actionable, the tracer object should be initialized with the OpenTracing implementation of your choice as in the pseudo-code below:

constCustomTracer=require('tracing-implementation-of-your-choice');

consttracer=newCustomTracer();

Usage in the browser

The package contains two bundles built with webpack that can be included using a standard <script> tag. The library will be exposed under the global opentracing namespace:

dist/opentracing-browser.min.js - minified, no runtime checks

dist/opentracing-browser.js - debug version with runtime checks

Usage with TypeScript

Since the source is written in TypeScript, if you are using TypeScript, you can just npm install the package and it will work out of the box.
This is especially useful for implementators who want to typecheck their implementation with the base interface.

Global tracer

The library also provides a global singleton tracer for convenience. This can be set and accessed via the following:

opentracing.initGlobalTracer(newCustomTracer());

consttracer=opentracing.globalTracer();

Note: globalTracer() returns a wrapper on the actual tracer object. This is done for convenience of use as it ensures that the function will always return a non-null object. This can be helpful in cases where it is difficult or impossible to know precisely when initGlobalTracer is called (for example, when writing a utility library that does not control the initialization process). For more precise control, individual Tracer objects can be used instead of the global tracer.

OpenTracing tracer implementations

This section is intended for developers wishing toimplement their own tracers. Developers who simply wish touse OpenTracingcan safely ignore this information.

Custom tracer implementation

Implementations can subclass opentracing.Trace, opentracing.Span, and the other API classes to build a OpenTracing tracer and implement the underscore prefixed methods such as _addTag to pick up a bit of common code implemented in the base classes.

API compatibility testing

If mocha is being used for unit testing, test/api_compatibility can be used to test the custom tracer. The file exports a single function that expects as an argument a function that will return a new instance of the tracer.