0
# OpenTelemetry Node SDK
1
2
OpenTelemetry Node SDK provides Node.js-specific tracing functionality that extends the base OpenTelemetry SDK with automatic AsyncLocalStorage-based context management. It enables seamless trace propagation across asynchronous operations in Node.js applications without manual context passing.
3
4
## Package Information
5
6
- **Package Name**: @opentelemetry/sdk-trace-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Node.js Version**: ^18.19.0 || >=20.6.0
10
- **Installation**: `npm install @opentelemetry/api @opentelemetry/sdk-trace-node`
11
12
## Core Imports
13
14
**Node.js-specific exports:**
15
16
```typescript
17
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
18
import type { NodeTracerConfig } from "@opentelemetry/sdk-trace-node";
19
```
20
21
CommonJS:
22
23
```javascript
24
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
25
```
26
27
**Available re-exports from @opentelemetry/sdk-trace-base:**
28
29
```typescript
30
// Classes and functions
31
import {
32
AlwaysOffSampler, AlwaysOnSampler, BasicTracerProvider,
33
BatchSpanProcessor, ConsoleSpanExporter, InMemorySpanExporter,
34
NoopSpanProcessor, ParentBasedSampler, RandomIdGenerator,
35
SamplingDecision, SimpleSpanProcessor, TraceIdRatioBasedSampler
36
} from "@opentelemetry/sdk-trace-node";
37
38
// Types
39
import type {
40
BatchSpanProcessorBrowserConfig, BufferConfig, GeneralLimits,
41
IdGenerator, ReadableSpan, Sampler, SamplingResult,
42
SDKRegistrationConfig, Span, SpanExporter, SpanLimits,
43
SpanProcessor, TimedEvent, TracerConfig
44
} from "@opentelemetry/sdk-trace-node";
45
```
46
47
## Basic Usage
48
49
```typescript
50
import { NodeTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
51
52
// Create NodeTracerProvider with automatic AsyncLocalStorage context management
53
const provider = new NodeTracerProvider();
54
55
// Add span processor
56
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
57
58
// Register automatically sets up:
59
// - AsyncLocalStorageContextManager for async context propagation
60
// - W3C Trace Context and Baggage propagators
61
provider.register();
62
63
// Traces will now automatically propagate across async operations
64
// without manual context passing
65
```
66
67
## Architecture
68
69
The Node SDK extends the base OpenTelemetry SDK with Node.js-specific functionality:
70
71
- **NodeTracerProvider**: Extends BasicTracerProvider with automatic Node.js context management setup
72
- **Automatic Context Management**: Sets up AsyncLocalStorageContextManager by default for async operation trace propagation
73
- **Automatic Propagation**: Configures W3C Trace Context and Baggage propagators by default
74
- **Base SDK Re-exports**: Provides access to all base tracing functionality (samplers, processors, exporters, etc.)
75
76
## Capabilities
77
78
### NodeTracerProvider
79
80
Node.js-specific tracer provider that extends BasicTracerProvider with automatic AsyncLocalStorage context management and propagator setup.
81
82
```typescript { .api }
83
/**
84
* NodeTracerProvider extends BasicTracerProvider with Node.js-specific functionality.
85
* Automatically configures AsyncLocalStorage for context management and W3C propagators.
86
*/
87
class NodeTracerProvider extends BasicTracerProvider {
88
/**
89
* Creates a new NodeTracerProvider instance
90
* @param config - Optional configuration (same as TracerConfig from base SDK)
91
*/
92
constructor(config?: NodeTracerConfig);
93
94
/**
95
* Register this TracerProvider for use with the OpenTelemetry API.
96
* Automatically sets up:
97
* - Global tracer provider
98
* - AsyncLocalStorageContextManager (unless null is provided)
99
* - W3C Trace Context and Baggage propagators (unless null is provided)
100
* @param config - Configuration object for SDK registration
101
*/
102
register(config?: SDKRegistrationConfig): void;
103
}
104
```
105
106
### Configuration
107
108
Configuration interfaces for NodeTracerProvider.
109
110
```typescript { .api }
111
/**
112
* Configuration for NodeTracerProvider - identical to TracerConfig from base SDK
113
*/
114
type NodeTracerConfig = TracerConfig;
115
116
/**
117
* Configuration for SDK registration controlling context manager and propagator setup
118
*/
119
interface SDKRegistrationConfig {
120
/**
121
* Context manager for trace context across async operations
122
* - undefined: Uses AsyncLocalStorageContextManager (default)
123
* - null: No context manager setup
124
* - ContextManager: Custom context manager
125
*/
126
contextManager?: ContextManager | null;
127
/**
128
* Propagator for trace context in requests
129
* - undefined: Uses W3C Trace Context + Baggage propagators (default)
130
* - null: No propagator setup
131
* - TextMapPropagator: Custom propagator
132
*/
133
propagator?: TextMapPropagator | null;
134
}
135
```
136
137
## Re-exported Base SDK Components
138
139
This package re-exports all functionality from `@opentelemetry/sdk-trace-base`, including:
140
141
- **Samplers**: `AlwaysOffSampler`, `AlwaysOnSampler`, `ParentBasedSampler`, `TraceIdRatioBasedSampler`
142
- **Processors**: `BatchSpanProcessor`, `SimpleSpanProcessor`, `NoopSpanProcessor`
143
- **Exporters**: `ConsoleSpanExporter`, `InMemorySpanExporter`
144
- **Base Provider**: `BasicTracerProvider`
145
- **Utilities**: `RandomIdGenerator`, `SamplingDecision`
146
- **Types**: All interfaces and types from the base SDK
147
148
For detailed documentation of these components, refer to the `@opentelemetry/sdk-trace-base` package documentation.
149
150
## Usage Examples
151
152
### Basic Setup with Automatic Context Management
153
154
```typescript
155
import { NodeTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
156
157
// Create provider - AsyncLocalStorage context management is automatic
158
const provider = new NodeTracerProvider();
159
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
160
161
// Register sets up everything needed for Node.js tracing
162
provider.register();
163
164
// Traces now automatically propagate across async operations
165
```
166
167
### Custom Context Manager Configuration
168
169
```typescript
170
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
171
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
172
173
const provider = new NodeTracerProvider();
174
175
// Use custom context manager
176
const customContextManager = new AsyncLocalStorageContextManager();
177
provider.register({
178
contextManager: customContextManager,
179
// propagator: undefined uses default W3C propagators
180
});
181
```
182
183
### Disable Automatic Setup
184
185
```typescript
186
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
187
188
const provider = new NodeTracerProvider();
189
190
// Register without automatic context manager or propagator setup
191
provider.register({
192
contextManager: null, // No context manager
193
propagator: null // No propagators
194
});
195
196
// Manual setup would be required in this case
197
```
198
199
### Node.js Async Context Propagation Example
200
201
```typescript
202
import { trace, SpanStatusCode } from '@opentelemetry/api';
203
import { NodeTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
204
205
// Setup
206
const provider = new NodeTracerProvider();
207
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
208
provider.register(); // Automatic AsyncLocalStorage setup
209
210
const tracer = trace.getTracer('my-service');
211
212
// Parent span
213
tracer.startActiveSpan('parent-operation', async (parentSpan) => {
214
215
// Child spans automatically inherit context across async operations
216
await new Promise(resolve => {
217
setTimeout(() => {
218
tracer.startActiveSpan('child-operation', (childSpan) => {
219
// This span is automatically linked to parent
220
childSpan.setStatus({ code: SpanStatusCode.OK });
221
childSpan.end();
222
resolve(undefined);
223
});
224
}, 100);
225
});
226
227
parentSpan.setStatus({ code: SpanStatusCode.OK });
228
parentSpan.end();
229
});
230
```