Medium/opentracing-javascript

Name: opentracing-javascript

Owner: Medium

Description: JavaScript implementation of Open Tracing API for the browser and server

Forked from: opentracing/opentracing-javascript

Created: 2016-07-25 19:11:00.0

Updated: 2016-07-25 19:11:02.0

Pushed: 2017-02-20 21:35:16.0

Homepage: null

Size: 216

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

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:

install --save opentracing

Example

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

 example

The output should look something like:

s:
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.

http = require('http');
opentracing = require('opentracing');

OTE: the default OpenTracing tracer does not record any tracing information.
eplace this line with the tracer implementation of your choice.
tracer = new opentracing.Tracer();

span = tracer.startSpan('http_request');
opts = {
host : 'example.com',
method: 'GET',
port : '80',
path: '/',

.request(opts, function (res) {
res.setEncoding('utf8');
res.on('error', function (err) {
    span.logEvent('request_error', err);
    span.finish();
});
res.on('data', function (chunk) {
    span.logEvent('data_received', chunk);
});
res.on('end', function(err) {
    span.logEvent('request_end', err);
    span.finish();
});
nd();

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:

CustomTracer = require('tracing-implementation-of-your-choice');
tracer = new CustomTracer();

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 symbol:

• dist/opentracing-browser.min.js - minified, no runtime checks
• dist/opentracing-browser.js - debug version with runtime checks

Global tracer

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

tracing.initGlobalTracer(new CustomTracer());

tracer = 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.

Node.js debug version

opentracing = require('opentracing/debug');

Requiring opentracing/debug will include a version of the library with additional runtime checks that are useful for debugging but not desirable for production use.

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 built using a Makefile. Run:

• make build creates the compiled, distributable code
• make test runs the tests

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.

Due to the dynamic nature of JavaScript, implementations can simply implement classes with the same signatures as the OpenTracing classes and use these directly as well (there's no need to subclass).

Lastly, optionally implementations may choose to subclass opentracing.Trace, etc. and implement the underscore prefixed methods such as _addTag to pick up a bit of common code implemented in the base classes. This is entirely optional.

API compatibility testing

If mocha is being used for unit testing, the api_compatibility.js file 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.

apiCompatibilityChecks = require('opentracing/test/api_compatibility.js');
ompatibilityCheck(function() {
 return new CustomTracer();

MockTracer

An minimal example tracer is provided in the src/mock_tracer directory of the source code.