0
# OpenTelemetry SDK Trace Base
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: @opentelemetry/sdk-trace-base
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`
10
11
**Important**: This package provides manual instrumentation only, NOT automatic instrumentation. It requires separate context management and propagation setup.
12
13
## Core Imports
14
15
```typescript
16
import {
17
BasicTracerProvider,
18
BatchSpanProcessor,
19
ConsoleSpanExporter,
20
SimpleSpanProcessor,
21
AlwaysOnSampler,
22
ParentBasedSampler,
23
TraceIdRatioBasedSampler
24
} from '@opentelemetry/sdk-trace-base';
25
```
26
27
For CommonJS:
28
29
```javascript
30
const {
31
BasicTracerProvider,
32
BatchSpanProcessor,
33
ConsoleSpanExporter
34
} = require('@opentelemetry/sdk-trace-base');
35
```
36
37
## Basic Usage
38
39
```typescript
40
import { BasicTracerProvider, BatchSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
41
import { Resource } from '@opentelemetry/resources';
42
import { trace, SpanStatusCode } from '@opentelemetry/api';
43
44
// Create tracer provider with configuration
45
const provider = new BasicTracerProvider({
46
resource: new Resource({
47
'service.name': 'my-service',
48
}),
49
spanProcessors: [
50
new BatchSpanProcessor(new ConsoleSpanExporter())
51
]
52
});
53
54
// Register the provider
55
trace.setGlobalTracerProvider(provider);
56
57
// Get a tracer and create spans
58
const tracer = trace.getTracer('my-service', '1.0.0');
59
60
const span = tracer.startSpan('my-operation');
61
span.setAttribute('user.id', '12345');
62
span.setStatus({ code: SpanStatusCode.OK });
63
span.end();
64
65
// Clean shutdown
66
await provider.forceFlush();
67
await provider.shutdown();
68
```
69
70
## Architecture
71
72
OpenTelemetry SDK Trace Base is built around several key components:
73
74
- **Tracer Provider**: Central registry and factory for creating tracers with shared configuration
75
- **Samplers**: Decision engines for determining which traces to collect and record
76
- **Span Processors**: Pipeline components for processing spans as they complete
77
- **Span Exporters**: Output handlers for sending span data to backends or storage
78
- **Platform Support**: Browser and Node.js specific optimizations for ID generation and batching
79
- **Type System**: Complete TypeScript interfaces and type definitions for all components
80
81
## Capabilities
82
83
### Tracer Provider
84
85
Core tracer provider implementation for creating and managing tracers with shared configuration across an application.
86
87
```typescript { .api }
88
class BasicTracerProvider {
89
constructor(config?: TracerConfig);
90
getTracer(name: string, version?: string, options?: { schemaUrl?: string }): Tracer;
91
forceFlush(): Promise<void>;
92
shutdown(): Promise<void>;
93
}
94
95
interface TracerConfig {
96
sampler?: Sampler;
97
generalLimits?: GeneralLimits;
98
spanLimits?: SpanLimits;
99
resource?: Resource;
100
idGenerator?: IdGenerator;
101
forceFlushTimeoutMillis?: number;
102
spanProcessors?: SpanProcessor[];
103
}
104
```
105
106
[Tracer Provider](./tracer-provider.md)
107
108
### Samplers
109
110
Sampling strategies for controlling which traces are collected, including always-on, ratio-based, and parent-aware samplers.
111
112
```typescript { .api }
113
interface Sampler {
114
shouldSample(
115
context: Context,
116
traceId: string,
117
spanName: string,
118
spanKind: SpanKind,
119
attributes: Attributes,
120
links: Link[]
121
): SamplingResult;
122
toString(): string;
123
}
124
125
enum SamplingDecision {
126
NOT_RECORD,
127
RECORD,
128
RECORD_AND_SAMPLED
129
}
130
```
131
132
[Samplers](./samplers.md)
133
134
### Span Processors
135
136
Pipeline processors for handling spans as they complete, including batching, immediate export, and no-op implementations.
137
138
```typescript { .api }
139
interface SpanProcessor {
140
forceFlush(): Promise<void>;
141
onStart(span: Span, parentContext: Context): void;
142
onEnd(span: ReadableSpan): void;
143
shutdown(): Promise<void>;
144
}
145
146
class SimpleSpanProcessor implements SpanProcessor {
147
constructor(exporter: SpanExporter);
148
}
149
150
class BatchSpanProcessor implements SpanProcessor {
151
constructor(exporter: SpanExporter, config?: BufferConfig);
152
}
153
```
154
155
[Span Processors](./span-processors.md)
156
157
### Span Exporters
158
159
Export implementations for sending span data to various destinations including console output and in-memory storage.
160
161
```typescript { .api }
162
interface SpanExporter {
163
export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
164
shutdown(): Promise<void>;
165
forceFlush?(): Promise<void>;
166
}
167
168
class ConsoleSpanExporter implements SpanExporter;
169
class InMemorySpanExporter implements SpanExporter;
170
```
171
172
[Span Exporters](./span-exporters.md)
173
174
### Platform Support
175
176
Platform-specific implementations providing optimized ID generation and batch processing for browser and Node.js environments.
177
178
```typescript { .api }
179
interface IdGenerator {
180
generateTraceId(): string;
181
generateSpanId(): string;
182
}
183
184
class RandomIdGenerator implements IdGenerator;
185
class BatchSpanProcessor implements SpanProcessor; // Platform-specific variants
186
```
187
188
[Platform Support](./platform.md)
189
190
## Core Types
191
192
```typescript { .api }
193
interface ReadableSpan {
194
readonly name: string;
195
readonly kind: SpanKind;
196
readonly spanContext: () => SpanContext;
197
readonly parentSpanContext?: SpanContext;
198
readonly startTime: HrTime;
199
readonly endTime: HrTime;
200
readonly status: SpanStatus;
201
readonly attributes: Attributes;
202
readonly links: Link[];
203
readonly events: TimedEvent[];
204
readonly duration: HrTime;
205
readonly ended: boolean;
206
readonly resource: Resource;
207
readonly instrumentationScope: InstrumentationScope;
208
readonly droppedAttributesCount: number;
209
readonly droppedEventsCount: number;
210
readonly droppedLinksCount: number;
211
}
212
213
interface GeneralLimits {
214
attributeValueLengthLimit?: number;
215
attributeCountLimit?: number;
216
}
217
218
interface SpanLimits {
219
attributeValueLengthLimit?: number;
220
attributeCountLimit?: number;
221
linkCountLimit?: number;
222
eventCountLimit?: number;
223
attributePerEventCountLimit?: number;
224
attributePerLinkCountLimit?: number;
225
}
226
227
interface BufferConfig {
228
maxExportBatchSize?: number;
229
scheduledDelayMillis?: number;
230
exportTimeoutMillis?: number;
231
maxQueueSize?: number;
232
}
233
234
interface TimedEvent {
235
time: HrTime;
236
name: string;
237
attributes?: Attributes;
238
droppedAttributesCount?: number;
239
}
240
```