0
# Base Instrumentation
1

2
The base instrumentation system provides the foundation for creating OpenTelemetry instrumentation modules that can automatically instrument third-party libraries and frameworks.
3

4
## Capabilities
5

6
### InstrumentationBase Class
7

8
Abstract base class that all instrumentation modules should extend. Provides lifecycle management, provider integration, and configuration handling.
9

10
```typescript { .api }
11
/**
12
 * Base abstract class for instrumenting node and web plugins
13
 */
14
abstract class InstrumentationBase<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
15
  extends InstrumentationAbstract<ConfigType> 
16
  implements Instrumentation<ConfigType> {
17
  
18
  constructor(
19
    instrumentationName: string,
20
    instrumentationVersion: string,
21
    config: ConfigType
22
  );
23

24
  /** Enable the instrumentation (implemented for Node.js) */
25
  enable(): void;
26

27
  /** Disable the instrumentation (implemented for Node.js) */
28
  disable(): void;
29

30
  /** Initialize and return module definitions */
31
  protected abstract init(): 
32
    | InstrumentationModuleDefinition 
33
    | InstrumentationModuleDefinition[] 
34
    | void;
35

36
  /** Set tracer provider */
37
  setTracerProvider(tracerProvider: TracerProvider): void;
38

39
  /** Set meter provider */
40
  setMeterProvider(meterProvider: MeterProvider): void;
41

42
  /** Set logger provider */
43
  setLoggerProvider?(loggerProvider: LoggerProvider): void;
44

45
  /** Set instrumentation configuration */
46
  setConfig(config: ConfigType): void;
47

48
  /** Get current configuration */
49
  getConfig(): ConfigType;
50

51
  /** Get module definitions (experimental) */
52
  getModuleDefinitions(): InstrumentationModuleDefinition[];
53
}
54
```
55

56
**Usage Example:**
57

58
```typescript
59
import { InstrumentationBase, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
60

61
class HttpInstrumentation extends InstrumentationBase {
62
  constructor(config = {}) {
63
    super("@opentelemetry/instrumentation-http", "1.0.0", config);
64
  }
65

66
  protected init() {
67
    return new InstrumentationNodeModuleDefinition(
68
      "http",
69
      ["*"],
70
      (moduleExports, moduleVersion) => {
71
        // Patch http module
72
        this._wrap(moduleExports, 'request', this._patchRequest.bind(this));
73
        return moduleExports;
74
      },
75
      (moduleExports, moduleVersion) => {
76
        // Unpatch http module  
77
        this._unwrap(moduleExports, 'request');
78
      }
79
    );
80
  }
81

82
  // enable() and disable() are implemented by the base class
83
  // No need to override unless custom behavior is required
84

85
  private _patchRequest(original: Function) {
86
    return function(this: any, ...args: any[]) {
87
      // Add tracing logic here
88
      return original.apply(this, args);
89
    };
90
  }
91
}
92
```
93

94
### InstrumentationAbstract (Base Class)
95

96
Core abstract class providing common instrumentation functionality.
97

98
```typescript { .api }
99
/**
100
 * Base abstract internal class for instrumenting node and web plugins
101
 */
102
abstract class InstrumentationAbstract<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
103
  implements Instrumentation<ConfigType> {
104
  
105
  readonly instrumentationName: string;
106
  readonly instrumentationVersion: string;
107

108
  constructor(
109
    instrumentationName: string,
110
    instrumentationVersion: string,
111
    config: ConfigType
112
  );
113

114
  /** Tracer instance */
115
  protected get tracer(): Tracer;
116

117
  /** Meter instance */
118
  protected get meter(): Meter;
119

120
  /** Logger instance */
121
  protected get logger(): Logger;
122

123
  /** Shimmer wrap function */
124
  protected _wrap: typeof wrap;
125

126
  /** Shimmer unwrap function */
127
  protected _unwrap: typeof unwrap;
128

129
  /** Shimmer mass wrap function */
130
  protected _massWrap: typeof massWrap;
131

132
  /** Shimmer mass unwrap function */
133
  protected _massUnwrap: typeof massUnwrap;
134

135
  /** Execute span customization hook safely */
136
  protected _runSpanCustomizationHook<SpanCustomizationInfoType>(
137
    hookHandler: SpanCustomizationHook<SpanCustomizationInfoType> | undefined,
138
    triggerName: string,
139
    span: Span,
140
    info: SpanCustomizationInfoType
141
  ): void;
142

143
  /** Update metric instruments (override in subclasses) */
144
  protected _updateMetricInstruments(): void;
145
}
146
```
147

148
### Configuration Management
149

150
Base configuration interface and management for all instrumentations.
151

152
```typescript { .api }
153
/**
154
 * Base interface for configuration options common to all instrumentations
155
 */
156
interface InstrumentationConfig {
157
  /** Whether to enable the plugin (default: true) */
158
  enabled?: boolean;
159
}
160
```
161

162
**Usage Example:**
163

164
```typescript
165
interface HttpInstrumentationConfig extends InstrumentationConfig {
166
  requestHook?: (span: Span, request: IncomingMessage) => void;
167
  responseHook?: (span: Span, response: ServerResponse) => void;
168
  ignoreIncomingRequestUrls?: (string | RegExp)[];
169
}
170

171
class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
172
  constructor(config: HttpInstrumentationConfig = {}) {
173
    super("@opentelemetry/instrumentation-http", "1.0.0", config);
174
  }
175

176
  // Use this.getConfig() to access configuration
177
  private _shouldIgnoreUrl(url: string): boolean {
178
    const config = this.getConfig();
179
    return config.ignoreIncomingRequestUrls?.some(pattern => 
180
      typeof pattern === 'string' ? url.includes(pattern) : pattern.test(url)
181
    ) ?? false;
182
  }
183
}
184
```
185

186
### Provider Integration
187

188
Integration with OpenTelemetry providers for distributed tracing, metrics, and logging.
189

190
```typescript { .api }
191
/**
192
 * Set tracer provider for this instrumentation
193
 */
194
setTracerProvider(tracerProvider: TracerProvider): void;
195

196
/**
197
 * Set meter provider for this instrumentation
198
 */
199
setMeterProvider(meterProvider: MeterProvider): void;
200

201
/**
202
 * Set logger provider for this instrumentation
203
 */
204
setLoggerProvider?(loggerProvider: LoggerProvider): void;
205
```
206

207
**Usage Example:**
208

209
```typescript
210
import { trace, metrics } from "@opentelemetry/api";
211
import { logs } from "@opentelemetry/api-logs";
212

213
const instrumentation = new HttpInstrumentation();
214

215
// Providers are usually set via registerInstrumentations
216
// but can be set directly if needed
217
instrumentation.setTracerProvider(trace.getTracerProvider());
218
instrumentation.setMeterProvider(metrics.getMeterProvider());
219
instrumentation.setLoggerProvider(logs.getLoggerProvider());
220
```
221

222
### Span Customization Hooks
223

224
System for allowing users to customize spans during instrumentation lifecycle events.
225

226
```typescript { .api }
227
/**
228
 * SpanCustomizationHook allows users to add custom behavior to spans
229
 */
230
type SpanCustomizationHook<SpanCustomizationInfoType> = (
231
  span: Span,
232
  info: SpanCustomizationInfoType
233
) => void;
234

235
/**
236
 * Execute span customization hook safely with error handling
237
 */
238
protected _runSpanCustomizationHook<SpanCustomizationInfoType>(
239
  hookHandler: SpanCustomizationHook<SpanCustomizationInfoType> | undefined,
240
  triggerName: string,
241
  span: Span,
242
  info: SpanCustomizationInfoType
243
): void;
244
```
245

246
**Usage Example:**
247

248
```typescript
249
interface HttpInstrumentationConfig extends InstrumentationConfig {
250
  requestHook?: SpanCustomizationHook<{ request: IncomingMessage }>;
251
}
252

253
class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
254
  private _onRequest(span: Span, request: IncomingMessage) {
255
    // Execute user-provided hook safely
256
    this._runSpanCustomizationHook(
257
      this.getConfig().requestHook,
258
      'request',
259
      span,
260
      { request }
261
    );
262
  }
263
}
264
```