IF Commons GitHub

otel

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-telemetry FR-001

The OpenTelemetry data model, written from the OpenTelemetry specification itself (commons 0001-telemetry FR-001 to FR-008): attribute values and log bodies, trace and span ids as brands made only from bytes the caller gives (the kernel has no randomness of its own), W3C Trace Context Level 2 traceparent and tracestate, resources, scopes, finished spans, log records and metric points, the configuration read from the OTEL_* environment variables (given as a record: the kernel reads no environment), redaction of what must never leave a process, the attribute, event and link limits, and the samplers OpenTelemetry names.

import { formatTraceparent, parseTraceparent, redactUrl, resolveConfig } from "./otel.ts";
const parent = parseTraceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
if (parent.kind === "ok") formatTraceparent(parent.value); // the same header back
redactUrl("https://user:pw@host/x?token=abc&page=2"); // "https://REDACTED:REDACTED@host/x?token=REDACTED&page=2"
resolveConfig({ OTEL_SERVICE_NAME: "build" }).config.resource; // { "service.name": "build" }

Source: commons/telemetry/src/otel.ts

51 of 146 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

otelnamespace
namespace otel
otel.AttributeValuetypeno test imports it
type AttributeValue =
  string | boolean | bigint | number | Uint8Array | readonly string[] | readonly boolean[] | readonly bigint[] | readonly number[];

An attribute's value: a string, a boolean, an integer (bigint, OTLP's int64), a double (number), bytes, or a homogeneous array of one of the primitive types. Nothing else is representable (FR-001).

otel.Attributestypeno test imports it
type Attributes = Readonly<Record<string, AttributeValue>>;

A set of attributes: names to values.

otel.AnyValuetypeno test imports it
type AnyValue = AttributeValue | readonly AnyValue[] | AnyMap;

A log body, as OTLP's AnyValue: what an attribute may be, and also a map or an array of mixed values (FR-001).

otel.AnyMaptypeno test imports it
type AnyMap = { readonly [key: string]: AnyValue };

A map of AnyValues, as OTLP's KeyValueList.

otel.TraceIdtypeno test imports it
type TraceId = Brand<string, "TraceId">;

A trace id: 32 lower-case hexadecimal digits, not all zeros (FR-002).

otel.SpanIdtypeno test imports it
type SpanId = Brand<string, "SpanId">;

A span id: 16 lower-case hexadecimal digits, not all zeros (FR-002).

otel.traceIdFromfunctionno test imports it
function traceIdFrom(bytes: Uint8Array<ArrayBufferLike>): Result<TraceId, string>

A trace id from 16 bytes a caller gives (traceIdFrom(random(16))); other lengths and all zeros are refused (FR-002).

otel.spanIdFromfunctionno test imports it
function spanIdFrom(bytes: Uint8Array<ArrayBufferLike>): Result<SpanId, string>

A span id from 8 bytes a caller gives (spanIdFrom(random(8))); other lengths and all zeros are refused (FR-002).

otel.parseTraceIdfunctionno test imports it
function parseTraceId(text: string): Result<TraceId, string>

A trace id from its text: 32 lower-case hexadecimal digits, not all zeros.

otel.parseSpanIdfunctionno test imports it
function parseSpanId(text: string): Result<SpanId, string>

A span id from its text: 16 lower-case hexadecimal digits, not all zeros.

otel.TraceStateMembertypeno test imports it
type TraceStateMember = { readonly key: string; readonly value: string };

One tracestate member.

otel.TraceStatetypeno test imports it
type TraceState = readonly TraceStateMember[];

A tracestate: its members, newest first, at most 32, each key once.

otel.SAMPLEDconstno test imports it
const SAMPLED: 1

The sampled trace flag.

otel.RANDOMconstno test imports it
const RANDOM: 2

The random trace flag of Level 2: the trace id's right-most 7 bytes are random.

otel.TRACESTATE_MAX_MEMBERSconstno test imports it
const TRACESTATE_MAX_MEMBERS: 32

The most members a tracestate keeps.

otel.SpanContexttypeno test imports it
type SpanContext = {
  readonly traceId: TraceId;
  readonly spanId: SpanId;
  readonly traceFlags: number;
  readonly traceState: TraceState;
  readonly isRemote: boolean;
};

What propagates: the ids, the flags, the trace state, and whether it came from another process.

otel.isSampledfunctionno test imports it
function isSampled(context: { readonly traceFlags: number; }): boolean

Whether a context's sampled flag is set.

otel.parseTraceparentfunctionno test imports it
function parseTraceparent(header: string): Result<SpanContext, string>

A traceparent header read (FR-003): version 00 exactly as written (55 characters, lower-case hexadecimal, ids not all zeros), version ff refused, a later version read by its first four fields. The context is remote and its trace state empty; the flags this version does not define are dropped.

otel.formatTraceparentfunctionno test imports it
function formatTraceparent(context: { readonly traceId: TraceId; readonly spanId: SpanId; readonly traceFlags: number; }): string

A traceparent header (version 00) for a context.

otel.isTraceStateKeyfunctionno test imports it
function isTraceStateKey(key: string): boolean

Whether a key is a tracestate key of the grammar.

otel.isTraceStateValuefunctionno test imports it
function isTraceStateValue(value: string): boolean

Whether a value is a tracestate value of the grammar.

otel.parseTracestatefunctionno test imports it
function parseTracestate(header: string): TraceState

A tracestate header read (FR-003): members split on commas with optional white space, a member that breaks the grammar or repeats a key dropped (never the header), at most 32 members kept. Several header fields are read joined with commas.

otel.formatTracestatefunctionno test imports it
function formatTracestate(state: TraceState): string

A tracestate header: the members newest first, as they are held.

otel.traceStateGetfunctionno test imports it
function traceStateGet(state: TraceState, key: string): string | undefined

The value of a key in a trace state.

otel.traceStateSetfunctionno test imports it
function traceStateSet(state: TraceState, key: string, value: string): Result<TraceState, string>

A trace state with a key set: the member moved to the front (newest), the oldest dropped beyond 32; a key or value of no grammar refused.

otel.traceStateDeletefunctionno test imports it
function traceStateDelete(state: TraceState, key: string): TraceState

A trace state without a key.

otel.extractContextfunctionno test imports it
function extractContext(traceparent: string | undefined, tracestate: string | undefined): SpanContext | undefined

The context carried by a traceparent and a tracestate (an HTTP request's headers, or the TRACEPARENT and TRACESTATE of the environment): undefined when there is no valid traceparent, whose tracestate is then ignored too.

otel.Resourcetypeno test imports it
type Resource = { readonly attributes: Attributes };

The entity that makes the signals: service.name and the others.

otel.Scopetypeno test imports it
type Scope = { readonly name: string; readonly version?: string; readonly attributes?: Attributes };

The instrumentation scope: the library or harness that makes the signals.

otel.SpanKindtypeno test imports it
type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";

A span's kind.

otel.SpanStatustypeno test imports it
type SpanStatus = { readonly kind: "unset" } | { readonly kind: "ok" } | { readonly kind: "error"; readonly message: string };

A span's status: unset, ok, or an error with its description.

otel.SpanEventtypeno test imports it
type SpanEvent = {
  readonly name: string;
  readonly time: bigint;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
};

Something that happened at a time during a span.

otel.SpanLinktypeno test imports it
type SpanLink = {
  readonly traceId: TraceId;
  readonly spanId: SpanId;
  readonly traceState: TraceState;
  readonly traceFlags: number;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
};

A span's link to another span's context.

otel.SpanDatatypeno test imports it
type SpanData = { readonly name: string; readonly context: SpanContext; readonly parentSpanId?: SpanId; readonly… (463 characters)
type SpanData = {
  readonly name: string;
  readonly context: SpanContext;
  readonly parentSpanId?: SpanId;
  readonly kind: SpanKind;
  readonly startTime: bigint;
  readonly endTime: bigint;
  readonly attributes: Attributes;
  readonly events: readonly SpanEvent[];
  readonly links: readonly SpanLink[];
  readonly status: SpanStatus;
  readonly droppedAttributesCount: number;
  readonly droppedEventsCount: number;
  readonly droppedLinksCount: number;
};

A finished span. Times are nanoseconds since the Unix epoch.

otel.SeverityNumbertypeno test imports it
type SeverityNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24;

A severity number of the log data model, 1 (TRACE) to 24 (FATAL4).

otel.SEVERITYconstno test imports it
const SEVERITY: { readonly TRACE: 1; readonly DEBUG: 5; readonly INFO: 9; readonly WARN: 13; readonly ERROR: 17; readonly FATAL: 21; }

The first severity number of each range of the log data model.

otel.isSeverityNumberfunctionno test imports it
function isSeverityNumber(n: number): n is SeverityNumber

Whether a number is a severity number (an integer from 1 to 24).

otel.severityTextfunctionno test imports it
function severityText(n: SeverityNumber): string

The short name the log data model gives a severity number: INFO, INFO2, ... FATAL4.

otel.LogRecordtypeno test imports it
type LogRecord = {
  readonly time: bigint;
  readonly observedTime: bigint;
  readonly severityNumber: SeverityNumber;
  readonly severityText: string;
  readonly body?: AnyValue;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
  readonly eventName?: string;
  readonly traceId?: TraceId;
  readonly spanId?: SpanId;
  readonly traceFlags?: number;
};

A log record. Times are nanoseconds since the Unix epoch.

otel.Temporalitytypeno test imports it
type Temporality = "delta" | "cumulative";

How a sum or a histogram accumulates: since the last collection, or since the series began.

otel.NumberPointtypeno test imports it
type NumberPoint = {
  readonly attributes: Attributes;
  readonly startTime: bigint;
  readonly time: bigint;
  readonly value: bigint | number;
};

A point of a sum or a gauge: an integer (bigint) or a double.

otel.HistogramPointtypeno test imports it
type HistogramPoint = {
  readonly attributes: Attributes;
  readonly startTime: bigint;
  readonly time: bigint;
  readonly count: number;
  readonly sum?: number;
  readonly min?: number;
  readonly max?: number;
  readonly bounds: readonly number[];
  readonly bucketCounts: readonly number[];
};

A point of an explicit-bucket histogram: bucketCounts has one more element than bounds, bucket i holding (bounds[i-1], bounds[i]].

otel.MetricDatatypeno test imports it
type MetricData =
  | { readonly kind: "sum"; readonly temporality: Temporality; readonly monotonic: boolean; readonly points: readonly NumberPoint[] }
  | { readonly kind: "gauge"; readonly points: readonly NumberPoint[] }
  | { readonly kind: "histogram"; readonly temporality: Temporality; readonly points: readonly HistogramPoint[] };

The data of a metric: a sum (monotonic or not), a gauge, or a histogram.

otel.Metrictypeno test imports it
type Metric = { readonly name: string; readonly description: string; readonly unit: string; readonly data: MetricData };

A metric: its name, description, unit and data.

otel.DEFAULT_HISTOGRAM_BOUNDSconstno test imports it
const DEFAULT_HISTOGRAM_BOUNDS: readonly number[]

OpenTelemetry's default explicit bucket bounds for a histogram (FR-013).

otel.Limitstypeno test imports it
type Limits = {
  readonly attributeValueLength: number;
  readonly attributeCount: number;
  readonly eventCount: number;
  readonly linkCount: number;
};

The limits of FR-005, applied by FR-007. attributeValueLength is Infinity where there is none.

otel.DEFAULT_LIMITSconstno test imports it
const DEFAULT_LIMITS: Limits

OpenTelemetry's default limits: no value length limit, 128 attributes, events and links.

otel.truncateValuefunctionno test imports it
function truncateValue(value: AttributeValue, length: number): AttributeValue

A value cut to the value length limit: a string, or each string of an array of strings; other values unchanged.

otel.mergeAttributesfunctionno test imports it
function mergeAttributes(current: Readonly<Record<string, AttributeValue>>, added: Readonly<Record<string, AttributeValue>>, limits: Pick<Limits, "attributeCount" | "attributeValueLength">): { readonly attributes: Readonly<Record<string, AttributeValue>>; readonly dropped: number; }

Attributes added to others under the limits (FR-007): a value cut to the length limit, an existing key replaced, a new key beyond the count dropped and counted.

otel.limitAttributesfunctionno test imports it
function limitAttributes(attributes: Readonly<Record<string, AttributeValue>>, limits: Pick<Limits, "attributeCount" | "attributeValueLength">): { readonly attributes: Readonly<Record<string, AttributeValue>>; readonly dropped: number; }

Attributes under the limits: what mergeAttributes gives from none.

otel.RootSamplertypeno test imports it
type RootSampler =
  { readonly kind: "always_on" } | { readonly kind: "always_off" } | { readonly kind: "traceidratio"; readonly ratio: number };

A sampler for a span with no parent.

otel.Samplertypeno test imports it
type Sampler = RootSampler | { readonly kind: "parentbased"; readonly root: RootSampler };

A sampler: a root sampler, or parentbased (the parent's sampled flag where there is a parent, root where there is none).

otel.DEFAULT_SAMPLERconstno test imports it
const DEFAULT_SAMPLER: Sampler

OpenTelemetry's default sampler: parentbased_always_on.

otel.ratioThresholdfunctionno test imports it
function ratioThreshold(ratio: number): bigint

The rejection threshold of TraceIdRatioBased for a ratio: a trace is sampled where its trace id's right-most 56 bits, read as an unsigned integer, are at least the threshold ((1 - ratio) * 2^56). Every process of a trace decides alike from the id alone.

otel.shouldSamplefunctionno test imports it
function shouldSample(sampler: Sampler, traceId: TraceId, parent: SpanContext | undefined): boolean

Whether a sampler samples a new span of a trace, given its parent (FR-008).

otel.REDACTEDconstno test imports it
const REDACTED: "REDACTED"

What a redacted secret is written as.

otel.isCredentialNamefunctionno test imports it
function isCredentialName(name: string): boolean

Whether a query parameter's or a field's name says it holds a credential (token, key, secret, password, signature, code, ...).

otel.redactUrlfunctionno test imports it
function redactUrl(url: string): string

A URL with its secrets replaced (FR-006): the user and password of its authority, and the value of each query parameter whose name says it is a credential, become REDACTED. The rest of the text is kept as written.

otel.isSecretFieldNamefunctionno test imports it
function isSecretFieldName(name: string): boolean

Whether a field's name in text says its value is a secret (FR-006): it ends in token, secret, password, passwd, passphrase, apikey, accesskey, secretkey, privatekey, credential or signature, with case, -, _ and . ignored (api_token, AWS_SECRET_ACCESS_KEY, X-Amz-Signature, clientSecret), but not max_tokens or token_type. Narrower than isCredentialName, which judges a URL's query parameters, because prose is full of code= and key:.

otel.redactTextfunctionno test imports it
function redactText(text: string, secrets?: Iterable<string>): string

Text with its secrets replaced (FR-006), the one redaction for signals and for what a harness mails: each exact secret named in secrets (four characters or more; a shorter one would garble the text and hide nothing), a private key block, each URL as redactUrl writes it, a bearer token, a basic credential (base64 of user:pass), the credential of an Authorization header with any scheme, the value of a name=value or name: value pair whose name isSecretFieldName judges secret (quoted or bare, in prose, JSON, YAML or an environment file), and the token formats that announce themselves (GitHub, GitLab, Slack, Google, Cloudflare, Anthropic, OpenAI, Stripe, npm, DigitalOcean, Docker, Hugging Face, Linear, Atlassian, JSON Web Tokens) and crypt password hashes become REDACTED.

otel.redactValuefunctionno test imports it
function redactValue(value: AttributeValue): AttributeValue

An attribute value with its secrets replaced: redactText on a string and on each string of an array.

otel.redactAnyValuefunctionno test imports it
function redactAnyValue(value: AnyValue): AnyValue

A log body with its secrets replaced, at every depth.

otel.redactAttributesfunctionno test imports it
function redactAttributes(attributes: Readonly<Record<string, AttributeValue>>, secretKeys?: Iterable<string>): Readonly<Record<string, AttributeValue>>

Attributes with the secret ones left out (never written, FR-006) and every other string redacted by redactText.

otel.commandShapefunctionno test imports it
function commandShape(argv: readonly string[]): readonly string[]

A command line as it may be recorded (FR-006): the program's name (its last path segment) and the names of its options alone, never a value, an operand or a subcommand. --opt=value is kept as --opt, a short option as its first letter (-pSECRET as -p), and nothing after --.

otel.SignalNametypeno test imports it
type SignalName = "traces" | "logs" | "metrics";

The three signals.

otel.ExporterConfigtypeno test imports it
type ExporterConfig = {
  readonly enabled: boolean;
  readonly endpoint: string | undefined;
  readonly headers: Readonly<Record<string, string>>;
  readonly timeoutMs: number;
};

Where and how one signal is exported. endpoint is undefined where none is configured (the runtime then probes the default).

otel.BatchConfigtypeno test imports it
type BatchConfig = {
  readonly scheduleDelayMs: number;
  readonly exportTimeoutMs: number;
  readonly maxQueueSize: number;
  readonly maxExportBatchSize: number;
};

The settings of a batch processor (OTEL_BSP_*, OTEL_BLRP_*).

otel.LogLeveltypeno test imports it
type LogLevel = "none" | "error" | "warn" | "info" | "debug" | "verbose" | "all";

The SDK's own log level (OTEL_LOG_LEVEL).

otel.OtelConfigtypeno test imports it
type OtelConfig = {
  readonly disabled: boolean;
  readonly resource: Attributes;
  readonly exporters: { readonly [S in SignalName]: ExporterConfig };
  readonly sampler: Sampler;
  readonly spanBatch: BatchConfig;
  readonly logBatch: BatchConfig;
  readonly metricExportIntervalMs: number;
  readonly metricExportTimeoutMs: number;
  readonly limits: Limits;
  readonly logLevel: LogLevel;
};

The configuration the OTEL_* variables give.

otel.DEFAULT_OTLP_ENDPOINTconstno test imports it
const DEFAULT_OTLP_ENDPOINT: "http://localhost:4318"

The endpoint an OTLP/HTTP exporter uses where none is configured.

otel.SIGNAL_PATHSconstno test imports it
const SIGNAL_PATHS: { readonly logs: string; readonly metrics: string; readonly traces: string; }

The path of each signal under a base endpoint.

otel.signalEndpointfunctionno test imports it
function signalEndpoint(base: string, signal: SignalName): string

A base endpoint with a signal's path appended, with one / between them.

otel.resolveConfigfunctionno test imports it
function resolveConfig(env: Readonly<Record<string, string | undefined>>): { readonly config: OtelConfig; readonly warnings: readonly string[]; }

The configuration of the OpenTelemetry environment variables, from a record of them (FR-005): the kernel reads no environment. A value that is not valid is a warning and its default is used; an empty value counts as unset; no vendor's variable is read. A protocol other than http/json is a warning and disables the export of that signal.

AttributeValuetype
type AttributeValue =
  string | boolean | bigint | number | Uint8Array | readonly string[] | readonly boolean[] | readonly bigint[] | readonly number[];

An attribute's value: a string, a boolean, an integer (bigint, OTLP's int64), a double (number), bytes, or a homogeneous array of one of the primitive types. Nothing else is representable (FR-001).

Imported by 24 tests of the run (24 passed, 0 failed): the library's results

Attributestype
type Attributes = Readonly<Record<string, AttributeValue>>;

A set of attributes: names to values.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

AnyValuetype
type AnyValue = AttributeValue | readonly AnyValue[] | AnyMap;

A log body, as OTLP's AnyValue: what an attribute may be, and also a map or an array of mixed values (FR-001).

Imported by 24 tests of the run (24 passed, 0 failed): the library's results

AnyMaptypeno test imports it
type AnyMap = { readonly [key: string]: AnyValue };

A map of AnyValues, as OTLP's KeyValueList.

TraceIdtype
type TraceId = Brand<string, "TraceId">;

A trace id: 32 lower-case hexadecimal digits, not all zeros (FR-002).

Imported by 36 tests of the run (36 passed, 0 failed): the library's results

SpanIdtype
type SpanId = Brand<string, "SpanId">;

A span id: 16 lower-case hexadecimal digits, not all zeros (FR-002).

Imported by 20 tests of the run (20 passed, 0 failed): the library's results

traceIdFromfunction
function traceIdFrom(bytes: Uint8Array<ArrayBufferLike>): Result<TraceId, string>

A trace id from 16 bytes a caller gives (traceIdFrom(random(16))); other lengths and all zeros are refused (FR-002).

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

spanIdFromfunction
function spanIdFrom(bytes: Uint8Array<ArrayBufferLike>): Result<SpanId, string>

A span id from 8 bytes a caller gives (spanIdFrom(random(8))); other lengths and all zeros are refused (FR-002).

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

parseTraceIdfunction
function parseTraceId(text: string): Result<TraceId, string>

A trace id from its text: 32 lower-case hexadecimal digits, not all zeros.

Imported by 43 tests of the run (43 passed, 0 failed): the library's results

parseSpanIdfunction
function parseSpanId(text: string): Result<SpanId, string>

A span id from its text: 16 lower-case hexadecimal digits, not all zeros.

Imported by 43 tests of the run (43 passed, 0 failed): the library's results

TraceStateMembertypeno test imports it
type TraceStateMember = { readonly key: string; readonly value: string };

One tracestate member.

TraceStatetype
type TraceState = readonly TraceStateMember[];

A tracestate: its members, newest first, at most 32, each key once.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SAMPLEDconstno test imports it
const SAMPLED: 1

The sampled trace flag.

RANDOMconstno test imports it
const RANDOM: 2

The random trace flag of Level 2: the trace id's right-most 7 bytes are random.

TRACESTATE_MAX_MEMBERSconstno test imports it
const TRACESTATE_MAX_MEMBERS: 32

The most members a tracestate keeps.

SpanContexttype
type SpanContext = {
  readonly traceId: TraceId;
  readonly spanId: SpanId;
  readonly traceFlags: number;
  readonly traceState: TraceState;
  readonly isRemote: boolean;
};

What propagates: the ids, the flags, the trace state, and whether it came from another process.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

isSampledfunctionno test imports it
function isSampled(context: { readonly traceFlags: number; }): boolean

Whether a context's sampled flag is set.

parseTraceparentfunction
function parseTraceparent(header: string): Result<SpanContext, string>

A traceparent header read (FR-003): version 00 exactly as written (55 characters, lower-case hexadecimal, ids not all zeros), version ff refused, a later version read by its first four fields. The context is remote and its trace state empty; the flags this version does not define are dropped.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

formatTraceparentfunction
function formatTraceparent(context: { readonly traceId: TraceId; readonly spanId: SpanId; readonly traceFlags: number; }): string

A traceparent header (version 00) for a context.

Imported by 36 tests of the run (36 passed, 0 failed): the library's results

isTraceStateKeyfunctionno test imports it
function isTraceStateKey(key: string): boolean

Whether a key is a tracestate key of the grammar.

isTraceStateValuefunctionno test imports it
function isTraceStateValue(value: string): boolean

Whether a value is a tracestate value of the grammar.

parseTracestatefunction
function parseTracestate(header: string): TraceState

A tracestate header read (FR-003): members split on commas with optional white space, a member that breaks the grammar or repeats a key dropped (never the header), at most 32 members kept. Several header fields are read joined with commas.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

formatTracestatefunction
function formatTracestate(state: TraceState): string

A tracestate header: the members newest first, as they are held.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

traceStateGetfunction
function traceStateGet(state: TraceState, key: string): string | undefined

The value of a key in a trace state.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

traceStateSetfunction
function traceStateSet(state: TraceState, key: string, value: string): Result<TraceState, string>

A trace state with a key set: the member moved to the front (newest), the oldest dropped beyond 32; a key or value of no grammar refused.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

traceStateDeletefunction
function traceStateDelete(state: TraceState, key: string): TraceState

A trace state without a key.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

extractContextfunction
function extractContext(traceparent: string | undefined, tracestate: string | undefined): SpanContext | undefined

The context carried by a traceparent and a tracestate (an HTTP request's headers, or the TRACEPARENT and TRACESTATE of the environment): undefined when there is no valid traceparent, whose tracestate is then ignored too.

Imported by 28 tests of the run (28 passed, 0 failed): the library's results

Resourcetype
type Resource = { readonly attributes: Attributes };

The entity that makes the signals: service.name and the others.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Scopetype
type Scope = { readonly name: string; readonly version?: string; readonly attributes?: Attributes };

The instrumentation scope: the library or harness that makes the signals.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SpanKindtype
type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";

A span's kind.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SpanStatustype
type SpanStatus = { readonly kind: "unset" } | { readonly kind: "ok" } | { readonly kind: "error"; readonly message: string };

A span's status: unset, ok, or an error with its description.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SpanEventtype
type SpanEvent = {
  readonly name: string;
  readonly time: bigint;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
};

Something that happened at a time during a span.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SpanLinktype
type SpanLink = {
  readonly traceId: TraceId;
  readonly spanId: SpanId;
  readonly traceState: TraceState;
  readonly traceFlags: number;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
};

A span's link to another span's context.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SpanDatatype
type SpanData = { readonly name: string; readonly context: SpanContext; readonly parentSpanId?: SpanId; readonly… (463 characters)
type SpanData = {
  readonly name: string;
  readonly context: SpanContext;
  readonly parentSpanId?: SpanId;
  readonly kind: SpanKind;
  readonly startTime: bigint;
  readonly endTime: bigint;
  readonly attributes: Attributes;
  readonly events: readonly SpanEvent[];
  readonly links: readonly SpanLink[];
  readonly status: SpanStatus;
  readonly droppedAttributesCount: number;
  readonly droppedEventsCount: number;
  readonly droppedLinksCount: number;
};

A finished span. Times are nanoseconds since the Unix epoch.

Imported by 39 tests of the run (39 passed, 0 failed): the library's results

SeverityNumbertype
type SeverityNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24;

A severity number of the log data model, 1 (TRACE) to 24 (FATAL4).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

SEVERITYconst
const SEVERITY: { readonly TRACE: 1; readonly DEBUG: 5; readonly INFO: 9; readonly WARN: 13; readonly ERROR: 17; readonly FATAL: 21; }

The first severity number of each range of the log data model.

Imported by 60 tests of the run (59 passed, 0 failed): the library's results

isSeverityNumberfunctionno test imports it
function isSeverityNumber(n: number): n is SeverityNumber

Whether a number is a severity number (an integer from 1 to 24).

severityTextfunction
function severityText(n: SeverityNumber): string

The short name the log data model gives a severity number: INFO, INFO2, ... FATAL4.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

LogRecordtype
type LogRecord = {
  readonly time: bigint;
  readonly observedTime: bigint;
  readonly severityNumber: SeverityNumber;
  readonly severityText: string;
  readonly body?: AnyValue;
  readonly attributes: Attributes;
  readonly droppedAttributesCount: number;
  readonly eventName?: string;
  readonly traceId?: TraceId;
  readonly spanId?: SpanId;
  readonly traceFlags?: number;
};

A log record. Times are nanoseconds since the Unix epoch.

Imported by 20 tests of the run (20 passed, 0 failed): the library's results

Temporalitytypeno test imports it
type Temporality = "delta" | "cumulative";

How a sum or a histogram accumulates: since the last collection, or since the series began.

NumberPointtype
type NumberPoint = {
  readonly attributes: Attributes;
  readonly startTime: bigint;
  readonly time: bigint;
  readonly value: bigint | number;
};

A point of a sum or a gauge: an integer (bigint) or a double.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

HistogramPointtype
type HistogramPoint = {
  readonly attributes: Attributes;
  readonly startTime: bigint;
  readonly time: bigint;
  readonly count: number;
  readonly sum?: number;
  readonly min?: number;
  readonly max?: number;
  readonly bounds: readonly number[];
  readonly bucketCounts: readonly number[];
};

A point of an explicit-bucket histogram: bucketCounts has one more element than bounds, bucket i holding (bounds[i-1], bounds[i]].

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

MetricDatatypeno test imports it
type MetricData =
  | { readonly kind: "sum"; readonly temporality: Temporality; readonly monotonic: boolean; readonly points: readonly NumberPoint[] }
  | { readonly kind: "gauge"; readonly points: readonly NumberPoint[] }
  | { readonly kind: "histogram"; readonly temporality: Temporality; readonly points: readonly HistogramPoint[] };

The data of a metric: a sum (monotonic or not), a gauge, or a histogram.

Metrictype
type Metric = { readonly name: string; readonly description: string; readonly unit: string; readonly data: MetricData };

A metric: its name, description, unit and data.

Imported by 20 tests of the run (20 passed, 0 failed): the library's results

DEFAULT_HISTOGRAM_BOUNDSconst
const DEFAULT_HISTOGRAM_BOUNDS: readonly number[]

OpenTelemetry's default explicit bucket bounds for a histogram (FR-013).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

Limitstypeno test imports it
type Limits = {
  readonly attributeValueLength: number;
  readonly attributeCount: number;
  readonly eventCount: number;
  readonly linkCount: number;
};

The limits of FR-005, applied by FR-007. attributeValueLength is Infinity where there is none.

DEFAULT_LIMITSconst
const DEFAULT_LIMITS: Limits

OpenTelemetry's default limits: no value length limit, 128 attributes, events and links.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

truncateValuefunctionno test imports it
function truncateValue(value: AttributeValue, length: number): AttributeValue

A value cut to the value length limit: a string, or each string of an array of strings; other values unchanged.

mergeAttributesfunction
function mergeAttributes(current: Readonly<Record<string, AttributeValue>>, added: Readonly<Record<string, AttributeValue>>, limits: Pick<Limits, "attributeCount" | "attributeValueLength">): { readonly attributes: Readonly<Record<string, AttributeValue>>; readonly dropped: number; }

Attributes added to others under the limits (FR-007): a value cut to the length limit, an existing key replaced, a new key beyond the count dropped and counted.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

limitAttributesfunction
function limitAttributes(attributes: Readonly<Record<string, AttributeValue>>, limits: Pick<Limits, "attributeCount" | "attributeValueLength">): { readonly attributes: Readonly<Record<string, AttributeValue>>; readonly dropped: number; }

Attributes under the limits: what mergeAttributes gives from none.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

RootSamplertypeno test imports it
type RootSampler =
  { readonly kind: "always_on" } | { readonly kind: "always_off" } | { readonly kind: "traceidratio"; readonly ratio: number };

A sampler for a span with no parent.

Samplertypeno test imports it
type Sampler = RootSampler | { readonly kind: "parentbased"; readonly root: RootSampler };

A sampler: a root sampler, or parentbased (the parent's sampled flag where there is a parent, root where there is none).

DEFAULT_SAMPLERconst
const DEFAULT_SAMPLER: Sampler

OpenTelemetry's default sampler: parentbased_always_on.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

ratioThresholdfunction
function ratioThreshold(ratio: number): bigint

The rejection threshold of TraceIdRatioBased for a ratio: a trace is sampled where its trace id's right-most 56 bits, read as an unsigned integer, are at least the threshold ((1 - ratio) * 2^56). Every process of a trace decides alike from the id alone.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

shouldSamplefunction
function shouldSample(sampler: Sampler, traceId: TraceId, parent: SpanContext | undefined): boolean

Whether a sampler samples a new span of a trace, given its parent (FR-008).

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

REDACTEDconstno test imports it
const REDACTED: "REDACTED"

What a redacted secret is written as.

isCredentialNamefunction
function isCredentialName(name: string): boolean

Whether a query parameter's or a field's name says it holds a credential (token, key, secret, password, signature, code, ...).

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

redactUrlfunction
function redactUrl(url: string): string

A URL with its secrets replaced (FR-006): the user and password of its authority, and the value of each query parameter whose name says it is a credential, become REDACTED. The rest of the text is kept as written.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

isSecretFieldNamefunction
function isSecretFieldName(name: string): boolean

Whether a field's name in text says its value is a secret (FR-006): it ends in token, secret, password, passwd, passphrase, apikey, accesskey, secretkey, privatekey, credential or signature, with case, -, _ and . ignored (api_token, AWS_SECRET_ACCESS_KEY, X-Amz-Signature, clientSecret), but not max_tokens or token_type. Narrower than isCredentialName, which judges a URL's query parameters, because prose is full of code= and key:.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

redactTextfunction
function redactText(text: string, secrets?: Iterable<string>): string

Text with its secrets replaced (FR-006), the one redaction for signals and for what a harness mails: each exact secret named in secrets (four characters or more; a shorter one would garble the text and hide nothing), a private key block, each URL as redactUrl writes it, a bearer token, a basic credential (base64 of user:pass), the credential of an Authorization header with any scheme, the value of a name=value or name: value pair whose name isSecretFieldName judges secret (quoted or bare, in prose, JSON, YAML or an environment file), and the token formats that announce themselves (GitHub, GitLab, Slack, Google, Cloudflare, Anthropic, OpenAI, Stripe, npm, DigitalOcean, Docker, Hugging Face, Linear, Atlassian, JSON Web Tokens) and crypt password hashes become REDACTED.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

redactValuefunctionno test imports it
function redactValue(value: AttributeValue): AttributeValue

An attribute value with its secrets replaced: redactText on a string and on each string of an array.

redactAnyValuefunctionno test imports it
function redactAnyValue(value: AnyValue): AnyValue

A log body with its secrets replaced, at every depth.

redactAttributesfunction
function redactAttributes(attributes: Readonly<Record<string, AttributeValue>>, secretKeys?: Iterable<string>): Readonly<Record<string, AttributeValue>>

Attributes with the secret ones left out (never written, FR-006) and every other string redacted by redactText.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

commandShapefunction
function commandShape(argv: readonly string[]): readonly string[]

A command line as it may be recorded (FR-006): the program's name (its last path segment) and the names of its options alone, never a value, an operand or a subcommand. --opt=value is kept as --opt, a short option as its first letter (-pSECRET as -p), and nothing after --.

Imported by 35 tests of the run (35 passed, 0 failed): the library's results

SignalNametype
type SignalName = "traces" | "logs" | "metrics";

The three signals.

Imported by 20 tests of the run (19 passed, 0 failed): the library's results

ExporterConfigtype
type ExporterConfig = {
  readonly enabled: boolean;
  readonly endpoint: string | undefined;
  readonly headers: Readonly<Record<string, string>>;
  readonly timeoutMs: number;
};

Where and how one signal is exported. endpoint is undefined where none is configured (the runtime then probes the default).

Imported by 20 tests of the run (19 passed, 0 failed): the library's results

BatchConfigtypeno test imports it
type BatchConfig = {
  readonly scheduleDelayMs: number;
  readonly exportTimeoutMs: number;
  readonly maxQueueSize: number;
  readonly maxExportBatchSize: number;
};

The settings of a batch processor (OTEL_BSP_*, OTEL_BLRP_*).

LogLeveltypeno test imports it
type LogLevel = "none" | "error" | "warn" | "info" | "debug" | "verbose" | "all";

The SDK's own log level (OTEL_LOG_LEVEL).

OtelConfigtype
type OtelConfig = {
  readonly disabled: boolean;
  readonly resource: Attributes;
  readonly exporters: { readonly [S in SignalName]: ExporterConfig };
  readonly sampler: Sampler;
  readonly spanBatch: BatchConfig;
  readonly logBatch: BatchConfig;
  readonly metricExportIntervalMs: number;
  readonly metricExportTimeoutMs: number;
  readonly limits: Limits;
  readonly logLevel: LogLevel;
};

The configuration the OTEL_* variables give.

Imported by 20 tests of the run (19 passed, 0 failed): the library's results

DEFAULT_OTLP_ENDPOINTconstno test imports it
const DEFAULT_OTLP_ENDPOINT: "http://localhost:4318"

The endpoint an OTLP/HTTP exporter uses where none is configured.

SIGNAL_PATHSconstno test imports it
const SIGNAL_PATHS: { readonly logs: string; readonly metrics: string; readonly traces: string; }

The path of each signal under a base endpoint.

signalEndpointfunction
function signalEndpoint(base: string, signal: SignalName): string

A base endpoint with a signal's path appended, with one / between them.

Imported by 20 tests of the run (19 passed, 0 failed): the library's results

resolveConfigfunction
function resolveConfig(env: Readonly<Record<string, string | undefined>>): { readonly config: OtelConfig; readonly warnings: readonly string[]; }

The configuration of the OpenTelemetry environment variables, from a record of them (FR-005): the kernel reads no environment. A value that is not valid is a warning and its default is used; an empty value counts as unset; no vendor's variable is read. A protocol other than http/json is a warning and disables the export of that signal.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.