TracingClient interface
Represents a client that can integrate with the currently configured Instrumenter.
Create an instance using createTracingClient.
Methods
| create |
Creates a set of request headers to propagate tracing information to a backend. |
| parse |
Parses a traceparent header value into a <xref:TracingSpanContext>. |
| start |
Starts a given span but does not set it as the active span. You must end the span using end. Most of the time you will want to use withSpan instead. |
| with |
Wraps a callback with an active context and calls the callback. Depending on the implementation, this may set the globally available active context. Useful when you want to leave the boundaries of the SDK (make a request or callback to user code) and are unable to use the withSpan API. |
| with |
Wraps a callback in a tracing span, calls the callback, and closes the span. This is the primary interface for using Tracing and will handle error recording as well as setting the status on the span. Both synchronous and asynchronous functions will be awaited in order to reflect the result of the callback on the span. Example: |
Method Details
createRequestHeaders(TracingContext)
Creates a set of request headers to propagate tracing information to a backend.
function createRequestHeaders(tracingContext?: TracingContext): Record<string, string>Parameters
- tracingContext
- TracingContext
The context containing the span to propagate.
Returns
Record<string, string>
The set of headers to add to a request.
parseTraceparentHeader(string)
Parses a traceparent header value into a <xref:TracingSpanContext>.
function parseTraceparentHeader(traceparentHeader: string): undefined | TracingContextParameters
- traceparentHeader
-
string
The traceparent header to parse.
Returns
undefined | TracingContext
An implementation-specific identifier for the span.
startSpan<Options>(string, Options, TracingSpanOptions)
Starts a given span but does not set it as the active span.
You must end the span using end.
Most of the time you will want to use withSpan instead.
function startSpan<Options>(name: string, operationOptions?: Options, spanOptions?: TracingSpanOptions): { span: TracingSpan, updatedOptions: OptionsWithTracingContext<Options> }Parameters
- name
-
string
The name of the span. By convention this should be ${className}.${methodName}.
- operationOptions
-
Options
The original operation options.
- spanOptions
- TracingSpanOptions
The options to use when creating the span.
Returns
{ span: TracingSpan, updatedOptions: OptionsWithTracingContext<Options> }
A TracingSpan and the updated operation options.
withContext<CallbackArgs, Callback>(TracingContext, Callback, CallbackArgs)
Wraps a callback with an active context and calls the callback. Depending on the implementation, this may set the globally available active context.
Useful when you want to leave the boundaries of the SDK (make a request or callback to user code) and are unable to use the withSpan API.
function withContext<CallbackArgs, Callback>(context: TracingContext, callback: Callback, callbackArgs: CallbackArgs): ReturnType<Callback>Parameters
- context
- TracingContext
The TracingContext to use as the active context in the scope of the callback.
- callback
-
Callback
The callback to be invoked with the given context set as the globally active context.
- callbackArgs
-
CallbackArgs
The callback arguments.
Returns
ReturnType<Callback>
withSpan<Options, Callback>(string, Options, Callback, TracingSpanOptions)
Wraps a callback in a tracing span, calls the callback, and closes the span.
This is the primary interface for using Tracing and will handle error recording as well as setting the status on the span.
Both synchronous and asynchronous functions will be awaited in order to reflect the result of the callback on the span.
Example:
const myOperationResult = await tracingClient.withSpan("myClassName.myOperationName", options, (updatedOptions) => myOperation(updatedOptions));
function withSpan<Options, Callback>(name: string, operationOptions: Options, callback: Callback, spanOptions?: TracingSpanOptions): Promise<Resolved<ReturnType<Callback>>>Parameters
- name
-
string
The name of the span. By convention this should be ${className}.${methodName}.
- operationOptions
-
Options
The original options passed to the method. The callback will receive these options with the newly created TracingContext.
- callback
-
Callback
The callback to be invoked with the updated options and newly created TracingSpan.
- spanOptions
- TracingSpanOptions
Returns
Promise<Resolved<ReturnType<Callback>>>