Interface PluginTypes.Tracer (8.0.0)

Package

Properties

constants

readonly constants: typeof Constants;

Well-known constant values used by the Trace Agent.

labels

readonly labels: typeof TraceLabels;

Well-known label keys for spans.

propagation

readonly propagation: Propagation;

A collection of functions for dealing with trace context in HTTP headers.

spanTypes

readonly spanTypes: typeof SpanType;

An enumeration of possible SpanType values.

traceContextUtils

readonly traceContextUtils: {
        encodeAsByteArray: (ctx: TraceContext) => Buffer;
        decodeFromByteArray: (buf: Buffer) => TraceContext | null;
    };

A collection of functions for encoding and decoding trace context.

Methods

createChildSpan(options)

createChildSpan(options?: SpanOptions): Span;

Creates and returns a new Span object nested within the current root span, which is detected automatically. If the root span is a phantom span or doesn't exist, the child span will be a phantom span as well.

Parameter
Name	Description
`options`	`SpanOptions` Options for creating the child span.

Returns
Type	Description
`Span`	A new Span object.

enhancedDatabaseReportingEnabled()

enhancedDatabaseReportingEnabled(): boolean;

Gets the value of enhancedDatabaseReporting in the trace agent's configuration object.

Returns
Type	Description
`boolean`	A boolean value indicating whether the trace agent was configured to have an enhanced level of reporting enabled.

getConfig()

getConfig(): StackdriverTracerConfig;

Gets the current configuration, or throws if it can't be retrieved because the Trace Agent was not disabled.

Returns
Type	Description
`StackdriverTracerConfig`

getCurrentContextId()

getCurrentContextId(): string | null;

Returns a unique identifier for the currently active context. This can be used to uniquely identify the current root span. If there is no current, context, or if we have lost context, this will return null. The structure and the length of the returned string should be treated opaquely - the only guarantee is that the value would unique for every root span.

Returns
Type	Description
`string \| null`	an id for the current context, or null if there is none

getCurrentRootSpan()

getCurrentRootSpan(): RootSpan;

Gets the active root span for the current context. This method is guaranteed to return an object with the surface of a RootSpan object, but it may not represent a real root span if we are not in one. Use isRealSpan or check the type field to determine whether this is a real or phantom span.

Returns
Type	Description
`RootSpan`	An object that represents either a real or phantom root span.

getProjectId()

getProjectId(): Promise<string>;

Returns the projectId that was either configured or auto-discovered by the TraceWriter.

Returns
Type	Description
`Promise<string>`

getResponseTraceContext(incomingTraceContext, isTraced)

getResponseTraceContext(incomingTraceContext: TraceContext | null, isTraced: boolean): TraceContext | null;

Generates a trace context object that should be set as the trace context header in a response to an incoming web request. This value is based on the trace context header value in the corresponding incoming request, as well as the result from the local trace policy on whether this request will be traced or not.

Parameters
Name	Description
`incomingTraceContext`	`TraceContext \| null` The trace context that was attached to the incoming web request, or null if the incoming request didn't have one.
`isTraced`	`boolean` Whether the incoming request was traced. This is determined by the local tracing policy.

Returns
Type	Description
`TraceContext \| null`	If the response should contain the trace context within its header, the context object to be serialized as this header's value. Otherwise, null.

getWriterProjectId()

getWriterProjectId(): string | null;

Returns the projectId that was either configured or auto-discovered by the TraceWriter. Note that the auto-discovery is done asynchronously, so this may return falsey until the projectId auto-discovery completes.

Returns
Type	Description
`string \| null`

isRealSpan(span)

isRealSpan(span: Span): boolean;

Returns whether a given span is real or not by checking its SpanType.

Parameter
Name	Description
`span`	`Span`

Returns
Type	Description
`boolean`

runInRootSpan(options, fn)

runInRootSpan<T>(options: RootSpanOptions, fn: (span: RootSpan) => T): T;

Runs the given function in a root span corresponding to an incoming request, passing it an object that exposes an interface for adding labels and closing the span.

Parameters
Name	Description
`options`	`RootSpanOptions` An object that specifies options for how the root span is created and propagated.
`fn`	`(span: RootSpan) => T` A function that will be called exactly once. If the incoming request should be traced, a root span will be created, and this function will be called with a Span object exposing functions operating on the root span; otherwise, it will be called with a phantom Span object.

Returns
Type	Description
`T`	The return value of calling fn.

Type Parameter
Name	Description
`T`

wrap(fn)

wrap<T>(fn: Func<T>): Func<T>;

Binds the trace context to the given function. This is necessary in order to create child spans correctly in functions that are called asynchronously (for example, in a network response handler).

Parameter
Name	Description
`fn`	`Func<T>` A function to which to bind the trace context.

Returns
Type	Description
`Func<T>`

Type Parameter
Name	Description
`T`

wrapEmitter(emitter)

wrapEmitter(emitter: EventEmitter): void;

Binds the trace context to the given event emitter. This is necessary in order to create child spans correctly in event handlers.

Parameter
Name	Description
`emitter`	`EventEmitter` An event emitter whose handlers should have the trace context binded to them.

Returns
Type	Description
`void`