JavaScript Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github Generate coverage only from Node-6 tests (#273) Jul 5, 2018
.vscode Prettify .js, .json files and add commit hook for auto formatting (#200) Jan 27, 2018
benchmarks Prettify .js, .json files and add commit hook for auto formatting (#200) Jan 27, 2018
crossdock Remove tchannel as tested transport in crossdock (#252) Apr 24, 2018
scripts Add a license checking script and add missing headers (#160) Nov 18, 2017
src Fix HTTP sender to work with TLS (#294) Aug 17, 2018
test Fix HTTP sender to work with TLS (#294) Aug 17, 2018
.babelrc Always build with Node 4 but test with all versions (#201) Jan 20, 2018
.eslintrc Prettify .js, .json files and add commit hook for auto formatting (#200) Jan 27, 2018
.flowconfig Upgrade flow to v0.75 (#272) Jul 4, 2018
.gitignore Use Xdock jaeger compose (#167) Nov 1, 2017
.gitmodules update gitmodules to use https Aug 31, 2016
.istanbul.yml Skip cover for _flow interfaces and only run npm cover as needed (#145) Aug 7, 2017
.jshintrc - added mocha tests and chai assertions Aug 5, 2016
.npmignore - add .npmignore, so that dist will show up even though its in Nov 2, 2016
.nvmrc Add .nvmrc to tell husky precommit which Node version to use (#227) Feb 20, 2018
.prettierrc Prettier Markdown files (#215) Jan 30, 2018
.travis.yml Generate coverage only from Node-6 tests (#273) Jul 5, 2018
CHANGELOG.md Back to development (#290) Aug 10, 2018
CONTRIBUTING.md Use different "good commit message" reference and inline it (#249) Apr 18, 2018
DCO Migrate to Apache license v2 (#159) Oct 9, 2017
LICENSE Migrate to Apache license v2 (#159) Oct 9, 2017
Makefile Generate coverage only from Node-6 tests (#273) Jul 5, 2018
README.md Add HTTP sender documentation (#286) Aug 11, 2018
RELEASE.md Back to development Feb 25, 2018
package.json Back to development (#290) Aug 10, 2018

README.md

Build Status Coverage Status NPM Published Version OpenTracing 1.0 Enabled

Jaeger Bindings for Javascript OpenTracing API

This is Jaeger's client side instrumentation library for Node.js that implements Javascript OpenTracing API 1.0.

Contributing and Developing

Please see CONTRIBUTING.md.

Installation

npm install --save jaeger-client

Initialization

The Tracer defaults to sending spans over UDP to the jaeger-agent running on localhost; the jaeger-agent handles forwarding the spans to the jaeger-collector.

var initTracer = require('jaeger-client').initTracer;

// See schema https://github.com/jaegertracing/jaeger-client-node/blob/master/src/configuration.js#L37
var config = {
  serviceName: 'my-awesome-service',
};
var options = {
  tags: {
    'my-awesome-service.version': '1.1.2',
  },
  metrics: metrics,
  logger: logger,
};
var tracer = initTracer(config, options);

Reporting spans via HTTP

UDP has a hard size limit of 65,507 bytes; if the span is larger than this limit, the tracer will drop the span. To circumvent this, you can configure the tracer to directly send spans to the jaeger-collector over HTTP (skipping the jaeger-agent altogether).

var initTracer = require('jaeger-client').initTracer;

// See schema https://github.com/jaegertracing/jaeger-client-node/blob/master/src/configuration.js#L37
var config = {
  serviceName: 'my-awesome-service',
  reporter: {
    // Provide the traces endpoint; this forces the client to connect directly to the Collector and send
    // spans over HTTP
    collectorEndpoint: 'http://jaeger-collector:14268/api/traces',
    // Provide username and password if authentication is enabled in the Collector
    // username: '',
    // password: '',
  },
};
var options = {
  tags: {
    'my-awesome-service.version': '1.1.2',
  },
  metrics: metrics,
  logger: logger,
};
var tracer = initTracer(config, options);

Metrics and Logging

The metrics and logger objects shown in the above example must satisfy the MetricsFactory and Logger APIs respectively.

Prometheus metrics

This module brings a Prometheus(prom-client) integration to the internal Jaeger metrics.
The way to initialize the tracer with Prometheus metrics:

var PrometheusMetricsFactory = require('jaeger-client').PrometheusMetricsFactory;
var promClient = require('prom-client');

var config = {
  serviceName: 'my-awesome-service',
};
var namespace = config.serviceName;
var metrics = new PrometheusMetricsFactory(promClient, namespace);
var options = {
  metrics: metrics,
};
var tracer = initTracer(config, options);

Usage

The Tracer instance created by initTracer is OpenTracing-1.0 compliant. See opentracing-javascript for usage examples.

TChannel Span Bridging

Because tchannel-node does not have instrumentation for OpenTracing, Jaeger-Client exposes methods wrapping tchannel handlers, and encoded channels. An encoded channel is a channel wrapped in either a thrift encoder TChannelAsThrift, or json encoder TChannelAsJson. To wrap a server handler for thrift one can initialize a tchannel bridge, and wrap the encoded handler function with a tracedHandler decorator. The tchannel bridge takes an OpenTracing tracer, and a context factory. The context factory must be a function that returns a context with the methods 'getSpan', and 'setSpan' which retrieve and assign the span to the context respectively.

import { TChannelBridge } from 'jaeger-client';
import Context from 'some-conformant-context';

function contextFactory() {
  return new Context();
}

let bridge = new TChannelBridge(tracer, { contextFactory: contextFactory });
let server = new TChannel({ serviceName: 'server' });
server.listen(4040, '127.0.0.1');
let serverThriftChannel = TChannelAsThrift({
  channel: server,
  entryPoint: path.join(__dirname, 'thrift', 'echo.thrift'), // file path to a thrift file
});

let perProcessOptions = {};
serverThriftChannel.register(
  server,
  'Echo::echo',
  perProcessOptions,
  bridge.tracedHandler((perProcessOptions, req, head, body, callback) => {
    /* Your handler code goes here. */
  })
);

Outbound calls can be made in two ways, shown below.

Using encoded channel to create a request and calling request.send()

import { TChannelBridge } from 'jaeger-client';

let bridge = new TChannelBridge(tracer);
// Create the toplevel client channel.
let client = new TChannel();

// Create the client subchannel that makes requests.
let clientSubChannel = client.makeSubChannel({
  serviceName: 'server',
  peers: ['127.0.0.1:4040'],
});

let encodedThriftChannel = TChannelAsThrift({
  channel: clientSubChannel,
  entryPoint: path.join(__dirname, 'thrift', 'echo.thrift'), // file path to a thrift file
});

// wrap encodedThriftChannel in a tracing decorator
let tracedChannel = bridge.tracedChannel(encodedThriftChannel);

// The encodedThriftChannel's (also true for json encoded channels) request object can call 'send' directly.
let req = tracedChannel.request({
  serviceName: 'server',
  context: context, // must be passed through from the service handler shown above
  headers: { cn: 'echo' },
});

// headers should contain your outgoing tchannel headers if any.
// In this instance 'send' is being called on the request object, and not the channel.
req.send('Echo::echo', headers, { value: 'some-string' });

Using top level channel to create a request and calling encodedChannel.send(request)

let tracedChannel = bridge.tracedChannel(encodedThriftChannel);

// tracedChannel.channel refers to encodedThriftChannel's inner channel which
// is clientSubChannel in this instance.
let req = tracedChannel.channel.request({
  serviceName: 'server',
  headers: { cn: 'echo' },
  context: context, // must be passed through from the service handler shown above
  timeout: someTimeout,
});
// send() can be called directly on the tracing decorator
tracedChannel.send(req, 'Echo::echo', o.headers, { value: 'some-string' }, clientCallback);

Debug Traces (Forced Sampling)

Programmatically

The OpenTracing API defines a sampling.priority standard tag that can be used to affect the sampling of a span and its children:

span.setTag(opentracing_tags.SAMPLING_PRIORITY, 1);

Via HTTP Headers

Jaeger Tracer also understands a special HTTP Header jaeger-debug-id, which can be set in the incoming request, e.g.

curl -H "jaeger-debug-id: some-correlation-id" http://myhost.com

When Jaeger sees this header in the request that otherwise has no tracing context, it ensures that the new trace started for this request will be sampled in the "debug" mode (meaning it should survive all downsampling that might happen in the collection pipeline), and the root span will have a tag as if this statement was executed:

span.setTag('jaeger-debug-id', 'some-correlation-id');

This allows using Jaeger UI to find the trace by this tag.

Zipkin Compatibility

Support for Zipkin's B3 Propagation HTTP headers is provided by the ZipkinB3TextMapCodec, which can be configured instead of the default TextMapCodec.

The new codec can be used by registering it with a tracer instance as both an injector and an extractor:

let codec = new ZipkinB3TextMapCodec({ urlEncoding: true });

tracer.registerInjector(opentracing.FORMAT_HTTP_HEADERS, codec);
tracer.registerExtractor(opentracing.FORMAT_HTTP_HEADERS, codec);

This can prove useful when compatibility with existing Zipkin tracing/instrumentation is desired.

License

Apache 2.0 License.