or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdplatform.mdsamplers.mdspan-exporters.mdspan-processors.mdtracer-provider.md
tile.json

tessl/npm-opentelemetry--sdk-trace-base

Foundational tracing SDK components for OpenTelemetry JavaScript providing manual instrumentation capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@opentelemetry/sdk-trace-base@2.1.x

To install, run

npx @tessl/cli install tessl/npm-opentelemetry--sdk-trace-base@2.1.0

index.mddocs/

OpenTelemetry SDK Trace Base

OpenTelemetry SDK Trace Base provides foundational tracing SDK components for OpenTelemetry JavaScript applications. It offers manual instrumentation capabilities including tracer providers, span processors, exporters, samplers, and platform-specific implementations for building distributed tracing solutions.

Package Information

  • Package Name: @opentelemetry/sdk-trace-base
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @opentelemetry/api @opentelemetry/sdk-trace-base

Important: This package provides manual instrumentation only, NOT automatic instrumentation. It requires separate context management and propagation setup.

Core Imports

import { 
  BasicTracerProvider,
  BatchSpanProcessor,
  ConsoleSpanExporter,
  SimpleSpanProcessor,
  AlwaysOnSampler,
  ParentBasedSampler,
  TraceIdRatioBasedSampler
} from '@opentelemetry/sdk-trace-base';

For CommonJS:

const { 
  BasicTracerProvider,
  BatchSpanProcessor,
  ConsoleSpanExporter 
} = require('@opentelemetry/sdk-trace-base');

Basic Usage

import { BasicTracerProvider, BatchSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
import { Resource } from '@opentelemetry/resources';
import { trace, SpanStatusCode } from '@opentelemetry/api';

// Create tracer provider with configuration
const provider = new BasicTracerProvider({
  resource: new Resource({
    'service.name': 'my-service',
  }),
  spanProcessors: [
    new BatchSpanProcessor(new ConsoleSpanExporter())
  ]
});

// Register the provider
trace.setGlobalTracerProvider(provider);

// Get a tracer and create spans
const tracer = trace.getTracer('my-service', '1.0.0');

const span = tracer.startSpan('my-operation');
span.setAttribute('user.id', '12345');
span.setStatus({ code: SpanStatusCode.OK });
span.end();

// Clean shutdown
await provider.forceFlush();
await provider.shutdown();

Architecture

OpenTelemetry SDK Trace Base is built around several key components:

  • Tracer Provider: Central registry and factory for creating tracers with shared configuration
  • Samplers: Decision engines for determining which traces to collect and record
  • Span Processors: Pipeline components for processing spans as they complete
  • Span Exporters: Output handlers for sending span data to backends or storage
  • Platform Support: Browser and Node.js specific optimizations for ID generation and batching
  • Type System: Complete TypeScript interfaces and type definitions for all components

Capabilities

Tracer Provider

Core tracer provider implementation for creating and managing tracers with shared configuration across an application.

class BasicTracerProvider {
  constructor(config?: TracerConfig);
  getTracer(name: string, version?: string, options?: { schemaUrl?: string }): Tracer;
  forceFlush(): Promise<void>;
  shutdown(): Promise<void>;
}

interface TracerConfig {
  sampler?: Sampler;
  generalLimits?: GeneralLimits;
  spanLimits?: SpanLimits;
  resource?: Resource;
  idGenerator?: IdGenerator;
  forceFlushTimeoutMillis?: number;
  spanProcessors?: SpanProcessor[];
}

Tracer Provider

Samplers

Sampling strategies for controlling which traces are collected, including always-on, ratio-based, and parent-aware samplers.

interface Sampler {
  shouldSample(
    context: Context,
    traceId: string,
    spanName: string,
    spanKind: SpanKind,
    attributes: Attributes,
    links: Link[]
  ): SamplingResult;
  toString(): string;
}

enum SamplingDecision {
  NOT_RECORD,
  RECORD,
  RECORD_AND_SAMPLED
}

Samplers

Span Processors

Pipeline processors for handling spans as they complete, including batching, immediate export, and no-op implementations.

interface SpanProcessor {
  forceFlush(): Promise<void>;
  onStart(span: Span, parentContext: Context): void;
  onEnd(span: ReadableSpan): void;
  shutdown(): Promise<void>;
}

class SimpleSpanProcessor implements SpanProcessor {
  constructor(exporter: SpanExporter);
}

class BatchSpanProcessor implements SpanProcessor {
  constructor(exporter: SpanExporter, config?: BufferConfig);
}

Span Processors

Span Exporters

Export implementations for sending span data to various destinations including console output and in-memory storage.

interface SpanExporter {
  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
  shutdown(): Promise<void>;
  forceFlush?(): Promise<void>;
}

class ConsoleSpanExporter implements SpanExporter;
class InMemorySpanExporter implements SpanExporter;

Span Exporters

Platform Support

Platform-specific implementations providing optimized ID generation and batch processing for browser and Node.js environments.

interface IdGenerator {
  generateTraceId(): string;
  generateSpanId(): string;
}

class RandomIdGenerator implements IdGenerator;
class BatchSpanProcessor implements SpanProcessor; // Platform-specific variants

Platform Support

Core Types

interface ReadableSpan {
  readonly name: string;
  readonly kind: SpanKind;
  readonly spanContext: () => SpanContext;
  readonly parentSpanContext?: SpanContext;
  readonly startTime: HrTime;
  readonly endTime: HrTime;
  readonly status: SpanStatus;
  readonly attributes: Attributes;
  readonly links: Link[];
  readonly events: TimedEvent[];
  readonly duration: HrTime;
  readonly ended: boolean;
  readonly resource: Resource;
  readonly instrumentationScope: InstrumentationScope;
  readonly droppedAttributesCount: number;
  readonly droppedEventsCount: number;
  readonly droppedLinksCount: number;
}

interface GeneralLimits {
  attributeValueLengthLimit?: number;
  attributeCountLimit?: number;
}

interface SpanLimits {
  attributeValueLengthLimit?: number;
  attributeCountLimit?: number;
  linkCountLimit?: number;
  eventCountLimit?: number;
  attributePerEventCountLimit?: number;
  attributePerLinkCountLimit?: number;
}

interface BufferConfig {
  maxExportBatchSize?: number;
  scheduledDelayMillis?: number;
  exportTimeoutMillis?: number;
  maxQueueSize?: number;
}

interface TimedEvent {
  time: HrTime;
  name: string;
  attributes?: Attributes;
  droppedAttributesCount?: number;
}