or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context.mdindex.mdplatform.mdpropagation.mdtiming.mdtrace-state.mdutilities.mdvalidation.md
tile.json

tessl/npm-opentelemetry--core

OpenTelemetry Core provides constants and utilities shared by all OpenTelemetry SDK packages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@opentelemetry/core@2.1.x

To install, run

npx @tessl/cli install tessl/npm-opentelemetry--core@2.1.0

index.mddocs/

OpenTelemetry Core

OpenTelemetry Core provides foundational constants, utilities, and implementations shared by all OpenTelemetry SDK packages. It includes built-in propagators for W3C Trace Context and Baggage, time handling utilities, platform abstractions, and error handling infrastructure that enable context sharing across distributed services.

Package Information

  • Package Name: @opentelemetry/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @opentelemetry/core

Core Imports

import {
  W3CTraceContextPropagator,
  W3CBaggagePropagator,
  CompositePropagator,
  TraceState,
  AnchoredClock
} from "@opentelemetry/core";

For CommonJS:

const {
  W3CTraceContextPropagator,
  W3CBaggagePropagator,
  CompositePropagator,
  TraceState,
  AnchoredClock
} = require("@opentelemetry/core");

Basic Usage

import {
  W3CTraceContextPropagator,
  W3CBaggagePropagator,
  CompositePropagator,
  TraceState,
  hrTime,
  sanitizeAttributes
} from "@opentelemetry/core";

// Create a composite propagator
const propagator = new CompositePropagator({
  propagators: [
    new W3CTraceContextPropagator(),
    new W3CBaggagePropagator(),
  ],
});

// Work with trace state
const traceState = new TraceState("key1=value1,key2=value2");
const updatedState = traceState.set("newkey", "newvalue");

// Get high-resolution time
const timestamp = hrTime();

// Sanitize attributes
const cleanAttrs = sanitizeAttributes({
  "user.id": "12345",
  "request.size": 1024,
  "valid": true
});

Architecture

OpenTelemetry Core is organized around several key architectural components:

  • Propagation System: W3C-compliant propagators for trace context and baggage with compositional design
  • Time Management: High-resolution timing utilities with nanosecond precision and monotonic clock support
  • Platform Abstraction: Cross-platform utilities for environment access, performance measurement, and SDK information
  • Context Management: Utilities for RPC metadata, trace suppression, and context manipulation
  • Validation & Sanitization: Attribute validation, error handling, and data sanitization
  • Utility Functions: Common utilities for merging, timeout handling, URL matching, and configuration parsing

Capabilities

Context Propagation

W3C-compliant propagators for distributed tracing and baggage propagation. Supports both trace context and baggage standards with compositional propagator patterns.

class W3CTraceContextPropagator implements TextMapPropagator {
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
  fields(): string[];
}

class W3CBaggagePropagator implements TextMapPropagator {
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
  fields(): string[];
}

class CompositePropagator implements TextMapPropagator {
  constructor(config?: CompositePropagatorConfig);
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
  fields(): string[];
}

Context Propagation

High-Resolution Timing

Nanosecond-precision timing utilities with monotonic clock support and various time format conversions. Essential for accurate span timing and performance measurement.

class AnchoredClock implements Clock {
  constructor(systemClock: Clock, monotonicClock: Clock);
  now(): number;
}

function hrTime(performanceNow?: number): HrTime;
function hrTimeDuration(startTime: HrTime, endTime: HrTime): HrTime;
function hrTimeToNanoseconds(time: HrTime): number;
function hrTimeToMilliseconds(time: HrTime): number;
function hrTimeToMicroseconds(time: HrTime): number;
function millisToHrTime(epochMillis: number): HrTime;

Timing Utilities

Trace State Management

W3C TraceState specification-compliant key-value store for vendor-specific trace information with immutable operations and serialization support.

class TraceState implements api.TraceState {
  constructor(rawTraceState?: string);
  get(key: string): string | undefined;
  set(key: string, value: string): TraceState;
  unset(key: string): TraceState;
  serialize(): string;
}

function parseTraceParent(traceParent: string): SpanContext | null;

Trace State

Platform Utilities

Cross-platform abstractions for environment variable access, performance measurement, SDK information, and timer utilities that work across Node.js and browser environments.

const SDK_INFO: object;
const _globalThis: object;
const otperformance: object;

function getBooleanFromEnv(key: string): boolean | undefined;
function getStringFromEnv(key: string): string | undefined;
function getNumberFromEnv(key: string): number | undefined;
function getStringListFromEnv(key: string, separator?: string): string[];
function unrefTimer(fn: Function, delay: number): any;

Platform Utilities

Context Management

Utilities for managing RPC metadata, trace suppression, and context manipulation including support for disabling tracing in specific execution contexts.

enum RPCType {
  HTTP = 'http'
}

function setRPCMetadata(context: Context, meta: RPCMetadata): Context;
function getRPCMetadata(context: Context): RPCMetadata | undefined;
function deleteRPCMetadata(context: Context): Context;

function suppressTracing(context: Context): Context;
function unsuppressTracing(context: Context): Context;
function isTracingSuppressed(context: Context): boolean;

Context Management

Data Validation & Error Handling

Attribute validation, sanitization, and comprehensive error handling infrastructure with global error handler support and logging integration.

function sanitizeAttributes(attributes: unknown): Attributes;
function isAttributeValue(val: unknown): val is AttributeValue;

function setGlobalErrorHandler(handler: ErrorHandler): void;
function globalErrorHandler(ex: Exception): void;
function loggingErrorHandler(): ErrorHandler;

enum ExportResultCode {
  SUCCESS,
  FAILED
}

interface ExportResult {
  code: ExportResultCode;
  error?: Error;
}

Validation & Error Handling

Utility Functions

Common utility functions including deep object merging, timeout handling, URL pattern matching, and configuration parsing that support various SDK operations.

function merge(...args: any[]): any;

class TimeoutError extends Error {}
function callWithTimeout<T>(promise: Promise<T>, timeout: number): Promise<T>;

function urlMatches(url: string, urlToMatch: string | RegExp): boolean;
function isUrlIgnored(url: string, ignoredUrls?: Array<string | RegExp>): boolean;

class BindOnceFuture<R, This, T> {
  constructor(callback: T, that: This);
  isCalled: boolean;
  promise: Promise<R>;
  call(...args: Parameters<T>): Promise<R>;
}

Utility Functions

Types

interface Clock {
  now(): number;
}

interface InstrumentationScope {
  readonly name: string;
  readonly version?: string;
  readonly schemaUrl?: string;
}

type ErrorHandler = (ex: Exception) => void;

interface CompositePropagatorConfig {
  propagators?: TextMapPropagator[];
}

type HTTPMetadata = {
  type: RPCType.HTTP;
  route?: string;
  span: Span;
};

type RPCMetadata = HTTPMetadata;