0
# OpenTelemetry Instrumentation
1

2
OpenTelemetry Instrumentation provides a foundational base class for creating instrumentation modules that automatically instrument third-party libraries and frameworks in both Node.js and browser environments. It offers a comprehensive API for hooking into module loading mechanisms, wrapping and unwrapping methods with tracing capabilities, and managing instrumentation lifecycle.
3

4
## Package Information
5

6
- **Package Name**: @opentelemetry/instrumentation
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @opentelemetry/instrumentation`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  InstrumentationBase, 
16
  registerInstrumentations, 
17
  InstrumentationNodeModuleDefinition, 
18
  InstrumentationNodeModuleFile,
19
  isWrapped,
20
  safeExecuteInTheMiddle,
21
  safeExecuteInTheMiddleAsync,
22
  SemconvStability,
23
  semconvStabilityFromStr,
24
  type Instrumentation,
25
  type InstrumentationConfig,
26
  type InstrumentationModuleDefinition,
27
  type InstrumentationModuleFile,
28
  type ShimWrapped,
29
  type SpanCustomizationHook,
30
  type AutoLoaderOptions,
31
  type AutoLoaderResult
32
} from "@opentelemetry/instrumentation";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const { 
39
  InstrumentationBase, 
40
  registerInstrumentations, 
41
  InstrumentationNodeModuleDefinition, 
42
  InstrumentationNodeModuleFile,
43
  isWrapped,
44
  safeExecuteInTheMiddle,
45
  safeExecuteInTheMiddleAsync,
46
  SemconvStability,
47
  semconvStabilityFromStr
48
} = require("@opentelemetry/instrumentation");
49
```
50

51
## Basic Usage
52

53
```typescript
54
import { InstrumentationBase, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
55

56
class MyInstrumentation extends InstrumentationBase {
57
  constructor(config = {}) {
58
    super("my-instrumentation", "1.0.0", config);
59
  }
60

61
  protected init() {
62
    return new InstrumentationNodeModuleDefinition(
63
      "target-module",
64
      [">=1.0.0 <2.0.0"],
65
      (moduleExports, moduleVersion) => {
66
        // Patch the module
67
        return moduleExports;
68
      },
69
      (moduleExports, moduleVersion) => {
70
        // Unpatch the module
71
      }
72
    );
73
  }
74

75
  enable() {
76
    // Enable instrumentation
77
  }
78

79
  disable() {
80
    // Disable instrumentation
81
  }
82
}
83

84
// Register the instrumentation
85
const unregister = registerInstrumentations({
86
  instrumentations: [new MyInstrumentation()]
87
});
88
```
89

90
## Architecture
91

92
OpenTelemetry Instrumentation is built around several key components:
93

94
- **InstrumentationBase**: Abstract base class providing core instrumentation functionality
95
- **Module Definition System**: Define which modules and versions to instrument with patch/unpatch functions
96
- **Auto-registration**: Automatic loading and lifecycle management of instrumentations
97
- **Platform Support**: Separate implementations for Node.js and browser environments
98
- **Provider Integration**: Seamless integration with TracerProvider, MeterProvider, and LoggerProvider
99
- **Safe Execution**: Error handling and recovery mechanisms for instrumentation operations
100

101
## Capabilities
102

103
### Base Instrumentation Class
104

105
Core abstract base class that instrumentation modules extend. Provides lifecycle management, provider integration, and configuration handling.
106

107
```typescript { .api }
108
abstract class InstrumentationBase<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
109
  implements Instrumentation<ConfigType> {
110
  abstract enable(): void;
111
  abstract disable(): void;
112
  setTracerProvider(tracerProvider: TracerProvider): void;
113
  setMeterProvider(meterProvider: MeterProvider): void;
114
  setLoggerProvider?(loggerProvider: LoggerProvider): void;
115
  setConfig(config: ConfigType): void;
116
  getConfig(): ConfigType;
117
}
118
```
119

120
[Base Instrumentation](./base-instrumentation.md)
121

122
### Module Definition System
123

124
System for defining which modules to instrument, their supported versions, and how to patch/unpatch them.
125

126
```typescript { .api }
127
class InstrumentationNodeModuleDefinition implements InstrumentationModuleDefinition {
128
  constructor(
129
    name: string,
130
    supportedVersions: string[],
131
    patch?: (exports: any, moduleVersion?: string) => any,
132
    unpatch?: (exports: any, moduleVersion?: string) => void,
133
    files?: InstrumentationModuleFile[]
134
  );
135
}
136

137
class InstrumentationNodeModuleFile implements InstrumentationModuleFile {
138
  constructor(
139
    name: string,
140
    supportedVersions: string[],
141
    patch: (moduleExports: any, moduleVersion?: string) => any,
142
    unpatch: (moduleExports?: any, moduleVersion?: string) => void
143
  );
144
}
145
```
146

147
[Module Definitions](./module-definitions.md)
148

149
### Auto-Registration System
150

151
Registration and lifecycle management system for instrumentations with provider configuration.
152

153
```typescript { .api }
154
function registerInstrumentations(options: AutoLoaderOptions): () => void;
155

156
interface AutoLoaderOptions {
157
  instrumentations?: (Instrumentation | Instrumentation[])[];
158
  tracerProvider?: TracerProvider;
159
  meterProvider?: MeterProvider;
160
  loggerProvider?: LoggerProvider;
161
}
162
```
163

164
[Auto-Registration](./auto-registration.md)
165

166
### Utility Functions
167

168
Safe execution utilities and function wrapping detection for robust instrumentation.
169

170
```typescript { .api }
171
function isWrapped(func: unknown): func is ShimWrapped;
172

173
function safeExecuteInTheMiddle<T>(
174
  execute: () => T,
175
  onFinish: (e: Error | undefined, result: T | undefined) => void,
176
  preventThrowingError?: boolean
177
): T;
178

179
function safeExecuteInTheMiddleAsync<T>(
180
  execute: () => T,
181
  onFinish: (e: Error | undefined, result: T | undefined) => void,
182
  preventThrowingError?: boolean
183
): Promise<T>;
184
```
185

186
[Utilities](./utilities.md)
187

188
### Semantic Convention Support
189

190
Support for semantic convention stability migration with namespace-specific configuration.
191

192
```typescript { .api }
193
enum SemconvStability {
194
  STABLE = 0x1,
195
  OLD = 0x2,
196
  DUPLICATE = 0x3
197
}
198

199
function semconvStabilityFromStr(
200
  namespace: string,
201
  str: string | undefined
202
): SemconvStability;
203
```
204

205
[Semantic Conventions](./semconv-stability.md)
206

207
## Core Types
208

209
```typescript { .api }
210
interface Instrumentation<ConfigType extends InstrumentationConfig = InstrumentationConfig> {
211
  instrumentationName: string;
212
  instrumentationVersion: string;
213
  disable(): void;
214
  enable(): void;
215
  setTracerProvider(tracerProvider: TracerProvider): void;
216
  setMeterProvider(meterProvider: MeterProvider): void;
217
  setLoggerProvider?(loggerProvider: LoggerProvider): void;
218
  setConfig(config: ConfigType): void;
219
  getConfig(): ConfigType;
220
}
221

222
interface InstrumentationConfig {
223
  enabled?: boolean;
224
}
225

226
interface InstrumentationModuleDefinition {
227
  name: string;
228
  moduleExports?: any;
229
  moduleVersion?: string;
230
  supportedVersions: string[];
231
  files: InstrumentationModuleFile[];
232
  includePrerelease?: boolean;
233
  patch?: (moduleExports: any, moduleVersion?: string) => any;
234
  unpatch?: (moduleExports: any, moduleVersion?: string) => void;
235
}
236

237
interface InstrumentationModuleFile {
238
  name: string;
239
  moduleExports?: unknown;
240
  supportedVersions: string[];
241
  patch(moduleExports: unknown, moduleVersion?: string): unknown;
242
  unpatch(moduleExports?: unknown, moduleVersion?: string): void;
243
}
244

245
interface ShimWrapped extends Function {
246
  __wrapped: boolean;
247
  __unwrap: Function;
248
  __original: Function;
249
}
250

251
type SpanCustomizationHook<SpanCustomizationInfoType> = (
252
  span: Span,
253
  info: SpanCustomizationInfoType
254
) => void;
255
```