src/plugin-types.ts
Represents the root span within a trace.
Methods |
createChildSpan | ||||||||
createChildSpan(options?: SpanOptions)
|
||||||||
Defined in src/plugin-types.ts:81
|
||||||||
Creates and starts a child span under this root span. If the root span is a real span (type = ROOT), the child span will be as well (type = CHILD). Otherwise, if the root span's type is UNTRACED or UNCORRELATED, the child span will be of the same type.
Parameters :
Returns :
Span
A new Span object. |
import {EventEmitter} from 'events';
import {Constants, SpanType} from './constants';
import {StackdriverTracerConfig} from './trace-api';
import {TraceLabels} from './trace-labels';
import {TraceContext} from './util';
export {TraceContext};
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type Func<T> = (...args: any[]) => T;
// Defines an interface for storing Trace-Agent related data on patched modules.
export interface TraceAgentExtension {
_google_trace_patched: boolean;
}
/**
* Represents a trace span.
*/
export interface Span {
/**
* Gets the current trace context, or null if it can't be retrieved.
* @return The trace context.
*/
getTraceContext(): TraceContext | null;
/**
* Adds a key-value pair as a label to the trace span. The value will be
* converted to a string if it is not already, and both the key and value may
* be truncated according to the user's configuration.
* @param key The label's key.
* @param value The label's value.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
addLabel(key: string, value: any): void;
/**
* The current span type. See `SpanType` for more information.
*/
readonly type: SpanType;
/**
* Ends the span. This method should only be called once.
* @param timestamp A custom span end time; defaults to the time when endSpan
* was called if not provided.
*/
endSpan(timestamp?: Date): void;
}
/**
* Represents the root span within a trace.
*/
export interface RootSpan extends Span {
/**
* Creates and starts a child span under this root span.
* If the root span is a real span (type = ROOT), the child span will be as
* well (type = CHILD).
* Otherwise, if the root span's type is UNTRACED or UNCORRELATED, the child
* span will be of the same type.
* @param options Options for creating the child span.
* @returns A new Span object.
*/
createChildSpan(options?: SpanOptions): Span;
}
/**
* An interface that describes the available options for creating a span in
* general.
*/
export interface SpanOptions {
/* The name to apply to the span. */
name: string;
/**
* The number of stack frames to skip when collecting call stack information
* for the span, starting from the top; this should be set to avoid including
* frames in the plugin. Defaults to 0.
*/
skipFrames?: number;
}
/**
* An interface that describes the available options for creating root spans.
*/
export interface RootSpanOptions extends SpanOptions {
/* A URL associated with the root span, if applicable. */
url?: string;
/* A Method associated with the root span, if applicable. */
method?: string;
/**
* An existing trace context, if it exists.
*/
traceContext?: TraceContext | null;
}
export interface Tracer {
/**
* Gets the value of enhancedDatabaseReporting in the trace agent's
* configuration object.
* @returns A boolean value indicating whether the trace agent was configured
* to have an enhanced level of reporting enabled.
*/
enhancedDatabaseReportingEnabled(): boolean;
/**
* Gets the current configuration, or throws if it can't be retrieved
* because the Trace Agent was not disabled.
*/
getConfig(): StackdriverTracerConfig;
/**
* 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.
* @param options An object that specifies options for how the root
* span is created and propagated.
* @param fn 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 The return value of calling fn.
*/
runInRootSpan<T>(options: RootSpanOptions, fn: (span: RootSpan) => T): T;
/**
* 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 An object that represents either a real or phantom root span.
*/
getCurrentRootSpan(): RootSpan;
/**
* 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 an id for the current context, or null if there is none
*/
getCurrentContextId(): string | null;
/**
* Returns the projectId that was either configured or auto-discovered by the
* TraceWriter.
*/
getProjectId(): Promise<string>;
/**
* 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.
*/
getWriterProjectId(): string | null;
/**
* 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.
* @param options Options for creating the child span.
* @returns A new Span object.
*/
createChildSpan(options?: SpanOptions): Span;
/**
* Returns whether a given span is real or not by checking its SpanType.
*/
isRealSpan(span: Span): boolean;
/**
* 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.
* @param incomingTraceContext The trace context that was attached to
* the incoming web request, or null if the incoming request didn't have one.
* @param isTraced Whether the incoming request was traced. This is determined
* by the local tracing policy.
* @returns If the response should contain the trace context within its
* header, the context object to be serialized as this header's value.
* Otherwise, null.
*/
getResponseTraceContext(
incomingTraceContext: TraceContext | null,
isTraced: boolean
): TraceContext | null;
/**
* 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).
* @param fn A function to which to bind the trace context.
*/
wrap<T>(fn: Func<T>): Func<T>;
/**
* Binds the trace context to the given event emitter.
* This is necessary in order to create child spans correctly in event
* handlers.
* @param emitter An event emitter whose handlers should have
* the trace context binded to them.
*/
wrapEmitter(emitter: EventEmitter): void;
/** Well-known constant values used by the Trace Agent. */
readonly constants: typeof Constants;
/** Well-known label keys for spans. */
readonly labels: typeof TraceLabels;
/** An enumeration of possible SpanType values. */
readonly spanTypes: typeof SpanType;
/** A collection of functions for encoding and decoding trace context. */
readonly traceContextUtils: {
encodeAsByteArray: (ctx: TraceContext) => Buffer;
decodeFromByteArray: (buf: Buffer) => TraceContext | null;
};
/**
* A collection of functions for dealing with trace context in HTTP headers.
*/
readonly propagation: Propagation;
}
export type GetHeaderFunction = (
key: string
) => string[] | string | null | undefined;
export type SetHeaderFunction = (key: string, value: string) => void;
export interface Propagation {
extract: (getHeader: GetHeaderFunction) => TraceContext | null;
inject: (
setHeader: SetHeaderFunction,
traceContext: TraceContext | null
) => void;
}
export interface Monkeypatch<T> {
file?: string;
versions?: string;
patch: (module: T, agent: Tracer) => void;
unpatch?: (module: T) => void;
}
export interface Intercept<T> {
file?: string;
versions?: string;
intercept: (module: T, agent: Tracer) => T;
}
export type Patch<T> = Monkeypatch<T> | Intercept<T>;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type Plugin = Array<Patch<any>>;