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
```