tessl/npm-opentelemetry--sdk-trace-base
Foundational tracing SDK components for OpenTelemetry JavaScript providing manual instrumentation capabilities
—
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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[];
}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
}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 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;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 variantsCore 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;
}Install with Tessl CLI
npx tessl i tessl/npm-opentelemetry--sdk-trace-base