Home Reference Source Repository
import Tracer from 'opentracing/src/tracer.js'
public class | source

Tracer

Direct Subclass:

Singleton

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

The default object acts as a no-op implementation.

Constructor Summary

Public Constructor
public

constructor(imp: *)

Note: this constructor should not be called directly by consumers of this code.

Method Summary

Public Methods
public

flush(done: function(err: objectg))

Request that any buffered or in-memory data is flushed out of the process.

public

imp(): object

Handle to implementation object.

public

inject(span: Span, format: string, carrier: any)

Injects the information about the given span into the carrier so that the span can propogate across inter-process barriers.

public

join(operationName: string, format: string, carrier: any): Span

Returns a new Span object with the given operation name using the trace information from the carrier.

public

startSpan(nameOrFields: string | object, fields: object): Span

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

Public Constructors

public constructor(imp: *) source

Note: this constructor should not be called directly by consumers of this code. The singleton's initNewTracer() method should be invoked instead.

Params:

NameTypeAttributeDescription
imp *

Public Methods

public flush(done: function(err: objectg)) source

Request that any buffered or in-memory data is flushed out of the process.

Params:

NameTypeAttributeDescription
done function(err: objectg)

optional callback function with the signature function(err) that will be called as soon as the flush completes. err should be null or undefined if the flush was successful.

public imp(): object source

Handle to implementation object.

Use of this method is discouraged as it greatly reduces the portability of the calling code. Use only when implementation-specific functionality must be used and cannot accessed otherwise.

Return:

object

An implementation-dependent object.

public inject(span: Span, format: string, carrier: any) source

Injects the information about the given span into the carrier so that the span can propogate across inter-process barriers.

See FORMAT_TEXT_MAP and FORMAT_BINARY for the two required carriers.

Consider this pseudocode example:

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

For FORMAT_BINARY, inject() will set the buffer field to an Array-like (Array, ArrayBuffer, or TypedBuffer) object containing the injected binary data. Any valid Object can be used as long as the buffer field of the object can be set.

Params:

NameTypeAttributeDescription
span Span

the span whose information should be injected into the carrier.

format string

the format of the carrier.

carrier any

see the method description for details on the carrier object.

public join(operationName: string, format: string, carrier: any): Span source

Returns a new Span object with the given operation name using the trace information from the carrier.

See FORMAT_TEXT_MAP and FORMAT_BINARY for the two required carriers.

Consider this pseudocode example:

// Use the inbound HTTP request's headers as a text map carrier.
var textCarrier = inboundHTTPReq.headers;
var serverSpan = Tracer.join(
    "operation name", Tracer.FORMAT_TEXT_MAP, textCarrier);

For FORMAT_BINARY, carrier is expected to have a field named buffer that contains an Array-like object (Array, ArrayBuffer, or TypedBuffer).

Params:

NameTypeAttributeDescription
operationName string

operation name to use on the newly created span.

format string

the format of the carrier.

carrier any

the type of the carrier object is determined by the format.

Return:

Span

public startSpan(nameOrFields: string | object, fields: object): Span source

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

Params:

NameTypeAttributeDescription
nameOrFields string | object

if the given argument is a string, it is the name of the operation and the second fields argument is optional. If it is an object, it is treated as the fields argument and a second argument should not be provided.

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.parent Span
  • optional

the parent of the newly created span

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.