@opentelemetry/api

@opentelemetry/api

Version 1.1.0
Published 3 months ago
647 kB
No dependencies
Apache-2.0 license

Install

npm i @opentelemetry/api

yarn add @opentelemetry/api

pnpm add @opentelemetry/api

Overview

Public API for OpenTelemetry

Index

Variables

variable _default

const _default: {
    trace: TraceAPI;
    context: ContextAPI;
    propagation: PropagationAPI;
    diag: DiagAPI;
};

variable context

const context: ContextAPI;

Entrypoint for context API

variable defaultTextMapGetter

const defaultTextMapGetter: TextMapGetter<any>;

variable defaultTextMapSetter

const defaultTextMapSetter: TextMapSetter<any>;

variable diag

const diag: DiagAPI;

Entrypoint for Diag API. Defines Diagnostic handler used for internal diagnostic logging operations. The default provides a Noop DiagLogger implementation which may be changed via the diag.setLogger(logger: DiagLogger) function.

variable INVALID_SPAN_CONTEXT

const INVALID_SPAN_CONTEXT: SpanContext;

variable INVALID_SPANID

const INVALID_SPANID: string;

variable INVALID_TRACEID

const INVALID_TRACEID: string;

variable propagation

const propagation: PropagationAPI;

Entrypoint for propagation API

variable ROOT_CONTEXT

const ROOT_CONTEXT: Context;

The root context is used as the default parent context when there is no active context

variable trace

const trace: TraceAPI;

Entrypoint for trace API

Functions

function baggageEntryMetadataFromString

baggageEntryMetadataFromString: (str: string) => BaggageEntryMetadata;

Create a serializable BaggageEntryMetadata object from a string.
Parameter str
string metadata. Format is currently not defined by the spec and has no special meaning.

function createContextKey

createContextKey: (description: string) => symbol;

Get a key to uniquely identify a context value

function createTraceState

createTraceState: (rawTraceState?: string) => TraceState;

function isSpanContextValid

isSpanContextValid: (spanContext: SpanContext) => boolean;

Returns true if this SpanContext is valid. true if this SpanContext is valid.

function isValidSpanId

isValidSpanId: (spanId: string) => boolean;

function isValidTraceId

isValidTraceId: (traceId: string) => boolean;

Classes

class ContextAPI

class ContextAPI {}

Singleton object which represents the entry point to the OpenTelemetry Context API

method active

active: () => Context;

Get the currently active context

method bind

bind: <T>(context: Context, target: T) => T;

Bind a context to a target function or event emitter
Parameter context
context to bind to the event emitter or function. Defaults to the currently active context
Parameter target
function or event emitter to bind

method disable

disable: () => void;

Disable and remove the global context manager

method getInstance

static getInstance: () => ContextAPI;

Get the singleton instance of the Context API

method setGlobalContextManager

setGlobalContextManager: (contextManager: ContextManager) => boolean;

Set the current context manager.
Returns
true if the context manager was successfully registered, else false

method with

with: <A extends unknown[], F extends (...args: A) => ReturnType<F>>(
    context: Context,
    fn: F,
    thisArg?: ThisParameterType<F>,
    ...args: A
) => ReturnType<F>;

Execute a function with an active context
Parameter context
context to be active during function execution
Parameter fn
function to execute in a context
Parameter thisArg
optional receiver to be used for calling fn
Parameter args
optional arguments forwarded to fn

class DiagAPI

class DiagAPI implements DiagLogger {}

Singleton object which represents the entry point to the OpenTelemetry internal diagnostic API

property createComponentLogger

createComponentLogger: (options: ComponentLoggerOptions) => DiagLogger;

property debug

debug: DiagLogFunction;

property disable

disable: () => void;

Unregister the global logger and return to Noop

property error

error: DiagLogFunction;

property info

info: DiagLogFunction;

property setLogger

setLogger: (logger: DiagLogger, logLevel?: DiagLogLevel) => boolean;

Set the global DiagLogger and DiagLogLevel. If a global diag logger is already set, this will override it.
Parameter logger
[Optional] The DiagLogger instance to set as the default logger.
Parameter logLevel
[Optional] The DiagLogLevel used to filter logs sent to the logger. If not provided it will default to INFO.
Returns
true if the logger was successfully registered, else false

property verbose

verbose: DiagLogFunction;

property warn

warn: DiagLogFunction;

method instance

static instance: () => DiagAPI;

Get the singleton instance of the DiagAPI API

class DiagConsoleLogger

class DiagConsoleLogger implements DiagLogger {}

A simple Immutable Console based diagnostic logger which will output any messages to the Console. If you want to limit the amount of logging to a specific level or lower use the createLogLevelDiagLogger

constructor

constructor();

property debug

debug: DiagLogFunction;

Log a general debug message that can be useful for identifying a failure. Information logged at this level may include diagnostic details that would help identify a failure scenario. Useful scenarios would be to log the execution order of async operations

property error

error: DiagLogFunction;

Log an error scenario that was not expected and caused the requested operation to fail.

property info

info: DiagLogFunction;

Log a general informational message, this should not affect functionality. This is also the default logging level so this should NOT be used for logging debugging level information.

property verbose

verbose: DiagLogFunction;

Log a detailed (verbose) trace level logging that can be used to identify failures where debug level logging would be insufficient, this level of tracing can include input and output parameters and as such may include PII information passing through the API. As such it is recommended that this level of tracing should not be enabled in a production environment.

property warn

warn: DiagLogFunction;

Log a warning scenario to inform the developer of an issues that should be investigated. The requested operation may or may not have succeeded or completed.

class PropagationAPI

class PropagationAPI {}

Singleton object which represents the entry point to the OpenTelemetry Propagation API

property createBaggage

createBaggage: (entries?: Record<string, BaggageEntry>) => Baggage;

property deleteBaggage

deleteBaggage: (context: Context) => Context;

property getBaggage

getBaggage: (context: Context) => Baggage;

property setBaggage

setBaggage: (context: Context, baggage: Baggage) => Context;

method disable

disable: () => void;

Remove the global propagator

method extract

extract: <Carrier>(
    context: Context,
    carrier: Carrier,
    getter?: TextMapGetter<Carrier>
) => Context;

Extract context from a carrier
Parameter context
Context which the newly created context will inherit from
Parameter carrier
Carrier to extract context from
Parameter getter
Function used to extract keys from a carrier

method fields

fields: () => string[];

Return a list of all fields which may be used by the propagator.

method getInstance

static getInstance: () => PropagationAPI;

Get the singleton instance of the Propagator API

method inject

inject: <Carrier>(
    context: Context,
    carrier: Carrier,
    setter?: TextMapSetter<Carrier>
) => void;

Inject context into a carrier to be propagated inter-process
Parameter context
Context carrying tracing data to inject
Parameter carrier
carrier to inject context into
Parameter setter
Function used to set values on the carrier

method setGlobalPropagator

setGlobalPropagator: (propagator: TextMapPropagator) => boolean;

Set the current propagator.
Returns
true if the propagator was successfully registered, else false

class ProxyTracer

class ProxyTracer implements Tracer {}

Proxy tracer provided by the proxy tracer provider

constructor

constructor(
    _provider: TracerDelegator,
    name: string,
    version?: string,
    options?: TracerOptions
);

property name

readonly name: string;

property options

readonly options?: TracerOptions;

property version

readonly version?: string;

method startActiveSpan

startActiveSpan: <F extends (span: Span) => unknown>(
    _name: string,
    _options: F | SpanOptions,
    _context?: F | Context,
    _fn?: F
) => ReturnType<F>;

method startSpan

startSpan: (name: string, options?: SpanOptions, context?: Context) => Span;

class ProxyTracerProvider

class ProxyTracerProvider implements TracerProvider {}

Tracer provider which provides ProxyTracers.
Before a delegate is set, tracers provided are NoOp. When a delegate is set, traces are provided from the delegate. When a delegate is set after tracers have already been provided, all tracers already provided will use the provided delegate implementation.

method getDelegate

getDelegate: () => TracerProvider;

method getDelegateTracer

getDelegateTracer: (
    name: string,
    version?: string,
    options?: TracerOptions
) => Tracer | undefined;

method getTracer

getTracer: (name: string, version?: string, options?: TracerOptions) => Tracer;

Get a ProxyTracer

method setDelegate

setDelegate: (delegate: TracerProvider) => void;

Set the delegate tracer provider

class TraceAPI

class TraceAPI {}

Singleton object which represents the entry point to the OpenTelemetry Tracing API

property deleteSpan

deleteSpan: (context: Context) => Context;

property getSpan

getSpan: (context: Context) => Span;

property getSpanContext

getSpanContext: (context: Context) => SpanContext;

property isSpanContextValid

isSpanContextValid: (spanContext: SpanContext) => boolean;

property setSpan

setSpan: (context: Context, span: Span) => Context;

property setSpanContext

setSpanContext: (context: Context, spanContext: SpanContext) => Context;

property wrapSpanContext

wrapSpanContext: (spanContext: SpanContext) => Span;

method disable

disable: () => void;

Remove the global tracer provider

method getInstance

static getInstance: () => TraceAPI;

Get the singleton instance of the Trace API

method getTracer

getTracer: (name: string, version?: string) => Tracer;

Returns a tracer from the global tracer provider.

method getTracerProvider

getTracerProvider: () => TracerProvider;

Returns the global tracer provider.

method setGlobalTracerProvider

setGlobalTracerProvider: (provider: TracerProvider) => boolean;

Set the current global tracer.
Returns
true if the tracer provider was successfully registered, else false

Interfaces

interface Attributes

interface Attributes {}

Attributes is a map from string to attribute values.
Note: only the own enumerable keys are counted as valid attribute keys.

index signature

[attributeKey: string]: AttributeValue | undefined;

interface Baggage

interface Baggage {}

Baggage represents collection of key-value pairs with optional metadata. Each key of Baggage is associated with exactly one value. Baggage may be used to annotate and enrich telemetry data.

method clear

clear: () => Baggage;

Returns a new baggage with no entries

method getAllEntries

getAllEntries: () => [string, BaggageEntry][];

Get a list of all entries in the Baggage

method getEntry

getEntry: (key: string) => BaggageEntry | undefined;

Get an entry from Baggage if it exists
Parameter key
The key which identifies the BaggageEntry

method removeEntries

removeEntries: (...key: string[]) => Baggage;

Returns a new baggage with the entries from the current bag except the removed entries
Parameter key
keys identifying the entries to be removed

method removeEntry

removeEntry: (key: string) => Baggage;

Returns a new baggage with the entries from the current bag except the removed entry
Parameter key
key identifying the entry to be removed

method setEntry

setEntry: (key: string, entry: BaggageEntry) => Baggage;

Returns a new baggage with the entries from the current bag and the specified entry
Parameter key
string which identifies the baggage entry
Parameter entry
BaggageEntry for the given key

interface BaggageEntry

interface BaggageEntry {}

property metadata

metadata?: BaggageEntryMetadata;

Metadata is an optional string property defined by the W3C baggage specification. It currently has no special meaning defined by the specification.

property value

value: string;

String value of the BaggageEntry.

interface ComponentLoggerOptions

interface ComponentLoggerOptions {}

Defines options for ComponentLogger

property namespace

namespace: string;

interface Context

interface Context {}

method deleteValue

deleteValue: (key: symbol) => Context;

Return a new context which inherits from this context but does not contain a value for the given key.
Parameter key
context key for which to clear a value

method getValue

getValue: (key: symbol) => unknown;

Get a value from the context.
Parameter key
key which identifies a context value

method setValue

setValue: (key: symbol, value: unknown) => Context;

Create a new context which inherits from this context and has the given key set to the given value.
Parameter key
context key for which to set the value
Parameter value
value to set for the given key

interface ContextManager

interface ContextManager {}

method active

active: () => Context;

Get the current active context

method bind

bind: <T>(context: Context, target: T) => T;

Bind an object as the current context (or a specific one)
Parameter context
Optionally specify the context which you want to assign
Parameter target
Any object to which a context need to be set

method disable

disable: () => this;

Disable context management

method enable

enable: () => this;

Enable context management

method with

with: <A extends unknown[], F extends (...args: A) => ReturnType<F>>(
    context: Context,
    fn: F,
    thisArg?: ThisParameterType<F>,
    ...args: A
) => ReturnType<F>;

Run the fn callback with object set as the current active context
Parameter context
Any object to set as the current active context
Parameter fn
A callback to be immediately run within a specific context
Parameter thisArg
optional receiver to be used for calling fn
Parameter args
optional arguments forwarded to fn

interface DiagLogger

interface DiagLogger {}

Defines an internal diagnostic logger interface which is used to log internal diagnostic messages, you can set the default diagnostic logger via the DiagAPI setLogger function. API provided implementations include :- - a No-Op createNoopDiagLogger - a DiagLogLevel filtering wrapper createLogLevelDiagLogger - a general Console DiagConsoleLogger version.

property debug

debug: DiagLogFunction;

Log a general debug message that can be useful for identifying a failure. Information logged at this level may include diagnostic details that would help identify a failure scenario. For example: Logging the order of execution of async operations.

property error

error: DiagLogFunction;

Log an error scenario that was not expected and caused the requested operation to fail.

property info

info: DiagLogFunction;

Log a general informational message, this should not affect functionality. This is also the default logging level so this should NOT be used for logging debugging level information.

property verbose

verbose: DiagLogFunction;

Log a detailed (verbose) trace level logging that can be used to identify failures where debug level logging would be insufficient, this level of tracing can include input and output parameters and as such may include PII information passing through the API. As such it is recommended that this level of tracing should not be enabled in a production environment.

property warn

warn: DiagLogFunction;

Log a warning scenario to inform the developer of an issues that should be investigated. The requested operation may or may not have succeeded or completed.

interface Link

interface Link {}

A pointer from the current Span to another span in the same trace or in a different trace. Few examples of Link usage. 1. Batch Processing: A batch of elements may contain elements associated with one or more traces/spans. Since there can only be one parent SpanContext, Link is used to keep reference to SpanContext of all elements in the batch. 2. Public Endpoint: A SpanContext in incoming client request on a public endpoint is untrusted from service provider perspective. In such case it is advisable to start a new trace with appropriate sampling decision. However, it is desirable to associate incoming SpanContext to new trace initiated on service provider side so two traces (from Client and from Service Provider) can be correlated.

property attributes

attributes?: SpanAttributes;

A set of SpanAttributes on the link.

property context

context: SpanContext;

The SpanContext of a linked span.

interface Sampler

interface Sampler {}

This interface represent a sampler. Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.

method shouldSample

shouldSample: (
    context: Context,
    traceId: string,
    spanName: string,
    spanKind: SpanKind,
    attributes: SpanAttributes,
    links: Link[]
) => SamplingResult;

Checks whether span needs to be created and tracked.
Parameter context
Parent Context which may contain a span.
Parameter traceId
of the span to be created. It can be different from the traceId in the SpanContext. Typically in situations when the span to be created starts a new trace.
Parameter spanName
of the span to be created.
Parameter spanKind
of the span to be created.
Parameter attributes
Initial set of SpanAttributes for the Span being constructed.
Parameter links
Collection of links that will be associated with the Span to be created. Typically useful for batch operations.
Returns
a SamplingResult.

method toString

toString: () => string;

Returns the sampler name or short description with the configuration.

interface SamplingResult

interface SamplingResult {}

A sampling result contains a decision for a Span and additional attributes the sampler would like to added to the Span.

property attributes

attributes?: Readonly<SpanAttributes>;

The list of attributes returned by SamplingResult MUST be immutable. Caller may call Sampler.shouldSample any number of times and can safely cache the returned value.

property decision

decision: SamplingDecision;

A sampling decision, refer to SamplingDecision for details.

interface Span

interface Span {}

An interface that represents a span. A span represents a single operation within a trace. Examples of span might include remote procedure calls or a in-process function calls to sub-components. A Trace has a single, top-level "root" Span that in turn may have zero or more child Spans, which in turn may have children.
Spans are created by the Tracer.startSpan method.

method addEvent

addEvent: (
    name: string,
    attributesOrStartTime?: SpanAttributes | TimeInput,
    startTime?: TimeInput
) => this;

Adds an event to the Span.
Parameter name
the name of the event.
Parameter attributesOrStartTime
the attributes that will be added; these are associated with this event. Can be also a start time if type is and 3rd param is undefined
Parameter startTime
start time of the event.

method end

end: (endTime?: TimeInput) => void;

Marks the end of Span execution.
Call to End of a Span MUST not have any effects on child spans. Those may still be running and can be ended later.
Do not return this. The Span generally should not be used after it is ended so chaining is not desired in this context.
Parameter endTime
the time to set as Span's end time. If not provided, use the current time as the span's end time.

method isRecording

isRecording: () => boolean;

Returns the flag whether this span will be recorded.
Returns
true if this Span is active and recording information like events with the AddEvent operation and attributes using setAttributes.

method recordException

recordException: (exception: Exception, time?: TimeInput) => void;

Sets exception as a span event
Parameter exception
the exception the only accepted values are string or Error
Parameter time
the time to set as Span's event time. If not provided, use the current time.

method setAttribute

setAttribute: (key: string, value: SpanAttributeValue) => this;

Sets an attribute to the span.
Sets a single Attribute with the key and value passed as arguments.
Parameter key
the key for this attribute.
Parameter value
the value for this attribute. Setting a value null or undefined is invalid and will result in undefined behavior.

method setAttributes

setAttributes: (attributes: SpanAttributes) => this;

Sets attributes to the span.
Parameter attributes
the attributes that will be added. null or undefined attribute values are invalid and will result in undefined behavior.

method setStatus

setStatus: (status: SpanStatus) => this;

Sets a status to the span. If used, this will override the default Span status. Default is SpanStatusCode.UNSET. SetStatus overrides the value of previous calls to SetStatus on the Span.
Parameter status
the SpanStatus to set.

method spanContext

spanContext: () => SpanContext;

Returns the SpanContext object associated with this Span.
Get an immutable, serializable identifier for this span that can be used to create new child spans. Returned SpanContext is usable even after the span ends.
Returns
the SpanContext object associated with this Span.

method updateName

updateName: (name: string) => this;

Updates the Span name.
This will override the name provided via Tracer.startSpan.
Upon this update, any sampling behavior based on Span name will depend on the implementation.
Parameter name
the Span name.

interface SpanContext

interface SpanContext {}

A SpanContext represents the portion of a Span which must be serialized and propagated along side of a Baggage.

property isRemote

isRemote?: boolean;

Only true if the SpanContext was propagated from a remote parent.

property spanId

spanId: string;

The ID of the Span. It is globally unique with practically sufficient probability by being made as 8 randomly generated bytes, encoded as a 16 lowercase hex characters corresponding to 64 bits.

property traceFlags

traceFlags: number;

Trace flags to propagate.
It is represented as 1 byte (bitmap). Bit to represent whether trace is sampled or not. When set, the least significant bit documents that the caller may have recorded trace data. A caller who does not record trace data out-of-band leaves this flag unset.
see TraceFlags for valid flag values.

property traceId

traceId: string;

The ID of the trace that this span belongs to. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes, encoded as a 32 lowercase hex characters corresponding to 128 bits.

property traceState

traceState?: TraceState;

Tracing-system-specific info to propagate.
The tracestate field value is a list as defined below. The list is a series of list-members separated by commas ,, and a list-member is a key/value pair separated by an equals sign =. Spaces and horizontal tabs surrounding list-members are ignored. There can be a maximum of 32 list-members in a list. More Info: https://www.w3.org/TR/trace-context/#tracestate-field
Examples: Single tracing system (generic format): tracestate: rojo=00f067aa0ba902b7 Multiple tracing systems (with different formatting): tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

interface SpanOptions

interface SpanOptions {}

Options needed for span creation

property attributes

attributes?: SpanAttributes;

A span's attributes

property kind

kind?: SpanKind;

The SpanKind of a span SpanKind.INTERNAL

property links

links?: Link[];

Links span to other spans

property root

root?: boolean;

The new span should be a root span. (Ignore parent from context).

property startTime

startTime?: TimeInput;

A manually specified start time for the created Span object.

interface SpanStatus

interface SpanStatus {}

property code

code: SpanStatusCode;

The status code of this message.

property message

message?: string;

A developer-facing error message.

interface TextMapGetter

interface TextMapGetter<Carrier = any> {}

A getter is specified by the caller to define a specific method to get the value of a key from a carrier.

method get

get: (carrier: Carrier, key: string) => undefined | string | string[];

Get the value of a specific key from the carrier.
Parameter carrier
Parameter key

method keys

keys: (carrier: Carrier) => string[];

Get a list of all keys available on the carrier.
Parameter carrier

interface TextMapPropagator

interface TextMapPropagator<Carrier = any> {}

Injects Context into and extracts it from carriers that travel in-band across process boundaries. Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as RPC/HTTP request headers.
The carrier of propagated data on both the client (injector) and server (extractor) side is usually an object such as http headers. Propagation is usually implemented via library-specific request interceptors, where the client-side injects values and the server-side extracts them.

method extract

extract: (
    context: Context,
    carrier: Carrier,
    getter: TextMapGetter<Carrier>
) => Context;

Given a Context and a carrier, extract context values from a carrier and return a new context, created from the old context, with the extracted values.
Parameter context
the Context from which to extract values to transmit over the wire.
Parameter carrier
the carrier of propagation fields, such as http request headers.
Parameter getter
an optional TextMapGetter. If undefined, keys will be all own properties, and keys will be accessed by direct object access.

method fields

fields: () => string[];

Return a list of all fields which may be used by the propagator.

method inject

inject: (
    context: Context,
    carrier: Carrier,
    setter: TextMapSetter<Carrier>
) => void;

Injects values from a given Context into a carrier.
OpenTelemetry defines a common set of format values (TextMapPropagator), and each has an expected carrier type.
Parameter context
the Context from which to extract values to transmit over the wire.
Parameter carrier
the carrier of propagation fields, such as http request headers.
Parameter setter
an optional TextMapSetter. If undefined, values will be set by direct object assignment.

interface TextMapSetter

interface TextMapSetter<Carrier = any> {}

A setter is specified by the caller to define a specific method to set key/value pairs on the carrier within a propagator.

method set

set: (carrier: Carrier, key: string, value: string) => void;

Callback used to set a key/value pair on an object.
Should be called by the propagator each time a key/value pair should be set, and should set that key/value pair on the propagator.
Parameter carrier
object or class which carries key/value pairs
Parameter key
string key to modify
Parameter value
value to be set to the key on the carrier

interface Tracer

interface Tracer {}

Tracer provides an interface for creating Spans.

method startActiveSpan

startActiveSpan: {
    <F extends (span: Span) => unknown>(name: string, fn: F): ReturnType<F>;
    <F extends (span: Span) => unknown>(
        name: string,
        options: SpanOptions,
        fn: F
    ): ReturnType<F>;
    <F extends (span: Span) => unknown>(
        name: string,
        options: SpanOptions,
        context: Context,
        fn: F
    ): ReturnType<F>;
};

Starts a new Span and calls the given function passing it the created span as first argument. Additionally the new span gets set in context and this context is activated for the duration of the function call.
Parameter name
The name of the span
Parameter options
SpanOptions used for span creation
Parameter context
Context to use to extract parent
Parameter fn
function called in the context of the span and receives the newly created span as an argument
Returns
return value of fn
Example 1
const something = tracer.startActiveSpan('op', span => { try { do some work span.setStatus({code: SpanStatusCode.OK}); return something; } catch (err) { span.setStatus({ code: SpanStatusCode.ERROR, message: err.message, }); throw err; } finally { span.end(); } });
Example 2
const span = tracer.startActiveSpan('op', span => { try { do some work return span; } catch (err) { span.setStatus({ code: SpanStatusCode.ERROR, message: err.message, }); throw err; } }); do some more work span.end();

method startSpan

startSpan: (name: string, options?: SpanOptions, context?: Context) => Span;

Starts a new Span. Start the span without setting it on context.
This method do NOT modify the current Context.
Parameter name
The name of the span
Parameter options
SpanOptions used for span creation
Parameter context
Context to use to extract parent
Returns
Span The newly created span
Example 1
const span = tracer.startSpan('op'); span.setAttribute('key', 'value'); span.end();

interface TracerDelegator

interface TracerDelegator {}

method getDelegateTracer

getDelegateTracer: (
    name: string,
    version?: string,
    options?: TracerOptions
) => Tracer | undefined;

interface TracerOptions

interface TracerOptions {}

An interface describes additional metadata of a tracer.

property schemaUrl

schemaUrl?: string;

The schemaUrl of the tracer or instrumentation library

interface TracerProvider

interface TracerProvider {}

A registry for creating named Tracers.

method getTracer

getTracer: (name: string, version?: string, options?: TracerOptions) => Tracer;

Returns a Tracer, creating one if one with the given name and version is not already created.
This function may return different Tracer types (e.g. NoopTracerProvider vs. a functional tracer).
Parameter name
The name of the tracer or instrumentation library.
Parameter version
The version of the tracer or instrumentation library.
Parameter options
The options of the tracer or instrumentation library.
Returns
Tracer A Tracer with the given name and version

interface TraceState

interface TraceState {}

method get

get: (key: string) => string | undefined;

Returns the value to which the specified key is mapped, or undefined if this map contains no mapping for the key.
Parameter key
with which the specified value is to be associated.
Returns
the value to which the specified key is mapped, or undefined if this map contains no mapping for the key.

method serialize

serialize: () => string;

Serializes the TraceState to a list as defined below. The list is a series of list-members separated by commas ,, and a list-member is a key/value pair separated by an equals sign =. Spaces and horizontal tabs surrounding list-members are ignored. There can be a maximum of 32 list-members in a list.
Returns
the serialized string.

method set

set: (key: string, value: string) => TraceState;

Create a new TraceState which inherits from this TraceState and has the given key set. The new entry will always be added in the front of the list of states.
Parameter key
key of the TraceState entry.
Parameter value
value of the TraceState entry.

method unset

unset: (key: string) => TraceState;

Return a new TraceState which inherits from this TraceState but does not contain the given key.
Parameter key
the key for the TraceState entry to be removed.

Enums

enum DiagLogLevel

enum DiagLogLevel {
    NONE = 0,
    ERROR = 30,
    WARN = 50,
    INFO = 60,
    DEBUG = 70,
    VERBOSE = 80,
    ALL = 9999,
}

Defines the available internal logging levels for the diagnostic logger, the numeric values of the levels are defined to match the original values from the initial LogLevel to avoid compatibility/migration issues for any implementation that assume the numeric ordering.

member ALL

ALL = 9999

Used to set the logging level to include all logging

member DEBUG

DEBUG = 70

General debug log message

member ERROR

ERROR = 30

Identifies an error scenario

member INFO

INFO = 60

General informational log message

member NONE

NONE = 0

Diagnostic Logging level setting to disable all logging (except and forced logs)

member VERBOSE

VERBOSE = 80

Detailed trace level logging should only be used for development, should only be set in a development environment.

member WARN

WARN = 50

Identifies a warning scenario

enum SamplingDecision

enum SamplingDecision {
    NOT_RECORD = 0,
    RECORD = 1,
    RECORD_AND_SAMPLED = 2,
}

A sampling decision that determines how a Span will be recorded and collected.

member NOT_RECORD

NOT_RECORD = 0

Span.isRecording() === false, span will not be recorded and all events and attributes will be dropped.

member RECORD

RECORD = 1

Span.isRecording() === true, but Sampled flag in TraceFlags MUST NOT be set.

member RECORD_AND_SAMPLED

RECORD_AND_SAMPLED = 2

Span.isRecording() === true AND Sampled flag in TraceFlags MUST be set.

enum SpanKind

enum SpanKind {
    INTERNAL = 0,
    SERVER = 1,
    CLIENT = 2,
    PRODUCER = 3,
    CONSUMER = 4,
}

member CLIENT

CLIENT = 2

Indicates that the span covers the client-side wrapper around an RPC or other remote request.

member CONSUMER

CONSUMER = 4

Indicates that the span describes consumer receiving a message from a broker. Unlike client and server, there is no direct critical path latency relationship between producer and consumer spans.

member INTERNAL

INTERNAL = 0

Default value. Indicates that the span is used internally.

member PRODUCER

PRODUCER = 3

Indicates that the span describes producer sending a message to a broker. Unlike client and server, there is no direct critical path latency relationship between producer and consumer spans.

member SERVER

SERVER = 1

Indicates that the span covers server-side handling of an RPC or other remote request.

enum SpanStatusCode

enum SpanStatusCode {
    UNSET = 0,
    OK = 1,
    ERROR = 2,
}

An enumeration of status codes.

member ERROR

ERROR = 2

The operation contains an error.

member OK

OK = 1

The operation has been validated by an Application developer or Operator to have completed successfully.

member UNSET

UNSET = 0

The default status.

enum TraceFlags

enum TraceFlags {
    NONE = 0,
    SAMPLED = 1,
}

member NONE

NONE = 0

Represents no flag set.

member SAMPLED

SAMPLED = 1

Bit to represent whether trace is sampled in trace flags.

Type Aliases

type AttributeValue

type AttributeValue =
    | string
    | number
    | boolean
    | Array<null | undefined | string>
    | Array<null | undefined | number>
    | Array<null | undefined | boolean>;

Attribute values may be any non-nullish primitive value except an object.
null or undefined attribute values are invalid and will result in undefined behavior.

type BaggageEntryMetadata

type BaggageEntryMetadata = {
    toString(): string;
} & {
    __TYPE__: typeof baggageEntryMetadataSymbol;
};

Serializable Metadata defined by the W3C baggage specification. It currently has no special meaning defined by the OpenTelemetry or W3C.

type DiagLogFunction

type DiagLogFunction = (message: string, ...args: unknown[]) => void;

type Exception

type Exception =
    | ExceptionWithCode
    | ExceptionWithMessage
    | ExceptionWithName
    | string;

Defines Exception.
string or an object with one of (message or name or code) and optional stack

type HrTime

type HrTime = [number, number];

Defines High-Resolution Time.
The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970. The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds. For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150. The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds: HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210. The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds: HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000. This is represented in HrTime format as [1609504210, 150000000].

type SpanAttributes

type SpanAttributes = Attributes;

Deprecated
please use Attributes

type SpanAttributeValue

type SpanAttributeValue = AttributeValue;

Deprecated
please use AttributeValue

type TimeInput

type TimeInput = HrTime | number | Date;

Defines TimeInput.
hrtime, epoch milliseconds, performance.now() or Date

Package Files (34)

Dependencies (0)

No dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@opentelemetry/api.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@opentelemetry/api)

HTML

<a href="https://www.jsdocs.io/package/@opentelemetry/api"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 3 months ago.
Package analyzed in 909 ms.
Missing or incorrect documentation? Open an issue for this package.

@opentelemetry/api

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Variables

variable _default

variable context

variable defaultTextMapGetter

variable defaultTextMapSetter

variable diag

variable INVALID_SPAN_CONTEXT

variable INVALID_SPANID

variable INVALID_TRACEID

variable propagation

variable ROOT_CONTEXT

variable trace

Functions

function baggageEntryMetadataFromString

Parameter str

function createContextKey

function createTraceState

function isSpanContextValid

function isValidSpanId

function isValidTraceId

Classes

class ContextAPI

method active

method bind

Parameter context

Parameter target

method disable

method getInstance

method setGlobalContextManager

Returns

method with

Parameter context

Parameter fn

Parameter thisArg

Parameter args

class DiagAPI

property createComponentLogger

property debug

property disable

property error

property info

property setLogger

Parameter logger

Parameter logLevel

Returns

property verbose

property warn

method instance

class DiagConsoleLogger

constructor

property debug

property error

property info

property verbose

property warn

class PropagationAPI

property createBaggage

property deleteBaggage

property getBaggage

property setBaggage

method disable

method extract

Parameter context

Parameter carrier

Parameter getter

method fields

method getInstance

method inject

Parameter context

Parameter carrier