opentracing-dm
v0.1.53
Published
[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![NPM Published Version][npm-img]][npm] ![Node Version][node-img]
Downloads
87
Readme
OpenTracing API for JavaScript
This library is a JavaScript implementation of Open Tracing API. It is intended for use both on the server and in the browser.
Required Reading
To fully understand this platform API, it's helpful to be familiar with the OpenTracing project and terminology more specifically.
Quick Start
Install the package using npm
:
npm install --save opentracing-dm
Example
The package contains an example using a DmTracer
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.
const http = require('http');
const opentracing = require('opentracing');
const tracer = require('opentracing-dm');
opentracing.initGlobalTracer(new tracer('https://dove.ideaportriga.lv', '35871aa4a79848eb943c880987a3b823'));
...
const tracer = opentracing.globalTracer();
const span = tracer.startSpan('http_request');
const opts = {
host : 'example.com',
method: 'GET',
port : '80',
path: '/',
};
http.request(opts, res => {
res.setEncoding('utf8');
res.on('error', err => {
// assuming no retries, mark the span as failed
span.setTag(opentracing.Tags.ERROR, true);
span.log({'event': 'error', 'error.object': err, 'message': err.message, 'stack': err.stack});
span.finish();
});
res.on('data', chunk => {
span.log({'event': 'data_received', 'chunk_length': chunk.length});
});
res.on('end', () => {
span.log({'event': 'request_end'});
span.finish();
});
}).end();
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:
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 checksdist/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.
API Documentation
There is a hosted copy of the current generated ESDoc API Documentation here.
Contributing & developer information
See the OpenTracing website for general information on contributing to OpenTracing.
The project is written in TypeScript and built using a npm scripts. Run:
npm run build
creates the compiled, distributable JavaScript code in./lib
npm run watch
incrementally compiles on file changesnpm run webpack
creates the bundles for the browser in./dist
npm test
runs the testsnpm run typedoc
generates the documentation in./typedoc
OpenTracing tracer implementations
This section is intended for developers wishing to implement their own tracers. Developers who simply wish to use OpenTracing can 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.
const apiCompatibilityChecks = require('opentracing/lib/test/api_compatibility.js').default;
apiCompatibilityChecks(() => new CustomTracer());
MockTracer
An minimal example tracer is provided in the src/mock_tracer
directory of the source code.