Package
@google-cloud/trace-agentProperties
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 |