Tracer
Direct Subclass:
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 |
|
public |
inject(spanContext: SpanContext, format: string, carrier: any): * Injects the given SpanContext instance for cross-process propagation
within |
|
public |
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 |
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 |
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 |
|
the fields to set on the newly created span. |
fields.operationName | string |
|
the name to use for the newly created span. Required if called with a single argument. |
fields.childOf | SpanContext |
|
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 | array |
|
an array of Reference instances,
each pointing to a causal parent SpanContext. If specified,
|
fields.tags | object |
|
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 |
|
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. |