import Tracer from 'opentracing/src/tracer.js'

public class | source

Tracer

Direct Subclass:

src/global_tracer.js~GlobalTracerDelegate

Tracer is the entry-point between the instrumentation API and the tracing implementation.

The default object acts as a no-op implementation.

Note to implementators: derived classes can choose to directly implement the methods in the "OpenTracing API methods" section, or optionally the subset of underscore-prefixed methods to pick up the argument checking and handling automatically from the base class.

Method Summary

Public Methods
public	extract(format: string, carrier: any): SpanContext Returns a SpanContext instance extracted from `carrier` in the given `format`.
public	inject(spanContext: SpanContext, format: string, carrier: any): * Injects the given SpanContext instance for cross-process propagation within `carrier`.
public	startSpan(name: string, fields: object): Span Starts and returns a new Span representing a logical unit of work.

Public Methods

public extract(format: string, carrier: any): SpanContext source

Returns a SpanContext instance extracted from carrier in the given format.

OpenTracing defines a common set of format values (see FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has an expected carrier type.

Consider this pseudocode example:

// Use the inbound HTTP request's headers as a text map carrier.
var headersCarrier = inboundHTTPReq.headers;
var wireCtx = Tracer.extract(Tracer.FORMAT_HTTP_HEADERS, headersCarrier);
var serverSpan = Tracer.startSpan('...', { childOf : wireCtx });

Params:

Name	Type	Attribute	Description
format	string		the format of the carrier.
carrier	any		the type of the carrier object is determined by the format.

Return:

SpanContext

The extracted SpanContext, or null if no such SpanContext could be found in carrier

public inject(spanContext: SpanContext, format: string, carrier: any): * source

Injects the given SpanContext instance for cross-process propagation within carrier. The expected type of carrier depends on the value of `format.

OpenTracing defines a common set of format values (see FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has an expected carrier type.

Consider this pseudocode example:

var clientSpan = ...;
...
// Inject clientSpan into a text carrier.
var headersCarrier = {};
Tracer.inject(clientSpan.context(), Tracer.FORMAT_HTTP_HEADERS, headersCarrier);
// Incorporate the textCarrier into the outbound HTTP request header
// map.
Object.assign(outboundHTTPReq.headers, headersCarrier);
// ... send the httpReq

Params:

Name	Type	Attribute	Description
spanContext	SpanContext		the SpanContext to inject into the carrier object. As a convenience, a Span instance may be passed in instead (in which case its .context() is used for the inject()).
format	string		the format of the carrier.
carrier	any		see the documentation for the chosen `format` for a description of the carrier object.

Return:

public startSpan(name: string, fields: object): Span source

Starts and returns a new Span representing a logical unit of work.

For example:

// Start a new (parentless) root Span:
var parent = Tracer.startSpan('DoWork');

// Start a new (child) Span:
var child = Tracer.startSpan('Subroutine', {
    childOf: parent.context(),
});

Params:

Name	Type	Attribute	Description
name	string		the name of the operation.
fields	object	optional	the fields to set on the newly created span.
fields.operationName	string	optional	the name to use for the newly created span. Required if called with a single argument.
fields.childOf	SpanContext	optional	a parent SpanContext (or Span, for convenience) that the newly-started span will be the child of (per REFERENCE_CHILD_OF). If specified, `fields.references` must be unspecified.
fields.references	array	optional	an array of Reference instances, each pointing to a causal parent SpanContext. If specified, `fields.childOf` must be unspecified.
fields.tags	object	optional	set of key-value pairs which will be set as tags on the newly created Span. Ownership of the object is passed to the created span for efficiency reasons (the caller should not modify this object after calling startSpan).
fields.startTime	number	optional	a manually specified start time for the created Span object. The time should be specified in milliseconds as Unix timestamp. Decimal value are supported to represent time values with sub-millisecond accuracy.

Return:

Span	a new Span object.