0
# OpenTelemetry HTTP Instrumentation
1

2
OpenTelemetry HTTP Instrumentation provides automatic telemetry collection for Node.js `http` and `https` modules. It captures distributed tracing data for both client requests and server operations, enabling comprehensive observability for HTTP communications with extensive configuration options.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
21
```
22

23
For configuration types:
24

25
```typescript
26
import { 
27
  HttpInstrumentation,
28
  type HttpInstrumentationConfig,
29
  type HttpCustomAttributeFunction,
30
  type IgnoreIncomingRequestFunction,
31
  type IgnoreOutgoingRequestFunction
32
} from "@opentelemetry/instrumentation-http";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
39
import { registerInstrumentations } from "@opentelemetry/instrumentation";
40

41
// Basic setup with default configuration
42
registerInstrumentations({
43
  instrumentations: [
44
    new HttpInstrumentation()
45
  ],
46
});
47

48
// With custom configuration
49
registerInstrumentations({
50
  instrumentations: [
51
    new HttpInstrumentation({
52
      // Ignore health check endpoints
53
      ignoreIncomingRequestHook: (req) => {
54
        return req.url?.includes('/health') === true;
55
      },
56
      // Add custom attributes to spans
57
      requestHook: (span, request) => {
58
        span.setAttribute('custom.user_agent', 
59
          request.headers['user-agent'] || 'unknown');
60
      },
61
      // Capture specific headers as span attributes
62
      headersToSpanAttributes: {
63
        client: {
64
          requestHeaders: ['authorization', 'content-type'],
65
          responseHeaders: ['content-type', 'server']
66
        },
67
        server: {
68
          requestHeaders: ['user-agent', 'referer'],
69
          responseHeaders: ['content-type']
70
        }
71
      }
72
    })
73
  ],
74
});
75
```
76

77
## Architecture
78

79
OpenTelemetry HTTP Instrumentation operates by monkey-patching Node.js built-in HTTP modules to automatically inject telemetry collection:
80

81
- **Module Instrumentation**: Patches `http` and `https` modules at the Node.js level
82
- **Span Creation**: Automatically creates spans for both incoming server requests and outgoing client requests
83
- **Attribute Collection**: Captures HTTP semantic conventions attributes (URL, method, status, headers, etc.)
84
- **Metrics Recording**: Records HTTP duration metrics for both client and server operations
85
- **Context Propagation**: Maintains distributed tracing context across HTTP boundaries
86
- **Configuration System**: Provides extensive hooks and options for customizing telemetry behavior
87

88
## Capabilities
89

90
### HTTP Instrumentation Class
91

92
Main instrumentation class that handles automatic HTTP telemetry collection for both client and server operations.
93

94
```typescript { .api }
95
class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
96
  constructor(config?: HttpInstrumentationConfig);
97
}
98
```
99

100
[HTTP Instrumentation](./http-instrumentation.md)
101

102
### Configuration Options
103

104
Comprehensive configuration interface for customizing HTTP instrumentation behavior including request filtering, custom attributes, and telemetry options.
105

106
```typescript { .api }
107
interface HttpInstrumentationConfig extends InstrumentationConfig {
108
  ignoreIncomingRequestHook?: IgnoreIncomingRequestFunction;
109
  ignoreOutgoingRequestHook?: IgnoreOutgoingRequestFunction;
110
  disableIncomingRequestInstrumentation?: boolean;
111
  disableOutgoingRequestInstrumentation?: boolean;
112
  applyCustomAttributesOnSpan?: HttpCustomAttributeFunction;
113
  requestHook?: HttpRequestCustomAttributeFunction;
114
  responseHook?: HttpResponseCustomAttributeFunction;
115
  startIncomingSpanHook?: StartIncomingSpanCustomAttributeFunction;
116
  startOutgoingSpanHook?: StartOutgoingSpanCustomAttributeFunction;
117
  serverName?: string;
118
  requireParentforOutgoingSpans?: boolean;
119
  requireParentforIncomingSpans?: boolean;
120
  headersToSpanAttributes?: {
121
    client?: { requestHeaders?: string[]; responseHeaders?: string[] };
122
    server?: { requestHeaders?: string[]; responseHeaders?: string[] };
123
  };
124
  enableSyntheticSourceDetection?: boolean;
125
  redactedQueryParams?: string[];
126
}
127
```
128

129
[Configuration](./configuration.md)
130

131
### Hook Functions
132

133
Custom function interfaces for filtering requests and adding custom attributes during HTTP instrumentation lifecycle events.
134

135
```typescript { .api }
136
interface IgnoreIncomingRequestFunction {
137
  (request: IncomingMessage): boolean;
138
}
139

140
interface IgnoreOutgoingRequestFunction {
141
  (request: RequestOptions): boolean;
142
}
143

144
interface HttpCustomAttributeFunction {
145
  (
146
    span: Span,
147
    request: ClientRequest | IncomingMessage,
148
    response: IncomingMessage | ServerResponse
149
  ): void;
150
}
151
```
152

153
[Hook Functions](./hook-functions.md)
154

155
## Types
156

157
### External Dependencies
158

159
The following types are from external modules used in the API signatures:
160

161
```typescript { .api }
162
// From @opentelemetry/api
163
interface Span {
164
  setAttribute(key: string, value: string | number | boolean | Array<string | number | boolean>): this;
165
  setStatus(status: { code: SpanStatusCode; message?: string }): this;
166
  recordException(exception: Exception): void;
167
  end(endTime?: TimeInput): void;  
168
  startTime: [number, number];
169
}
170

171
enum SpanStatusCode {
172
  UNSET = 0,
173
  OK = 1,
174
  ERROR = 2
175
}
176

177
type Exception = Error | string;
178
type TimeInput = [number, number] | number | Date;
179

180
interface Attributes {
181
  [key: string]: string | number | boolean | Array<string | number | boolean> | null | undefined;
182
}
183

184
// From @opentelemetry/instrumentation
185
class InstrumentationBase<T = any> {
186
  constructor(instrumentationName: string, instrumentationVersion: string, config?: T);
187
  enable(): void;
188
  disable(): void;
189
  setConfig(config: T): void;
190
  getConfig(): T;
191
  init(): InstrumentationNodeModuleDefinition[];
192
}
193

194
interface InstrumentationConfig {
195
  enabled?: boolean;
196
}
197

198
interface InstrumentationNodeModuleDefinition {
199
  name: string;
200
  moduleExports?: any;
201
  moduleVersion?: string;
202
  patch?: Function;
203
  unpatch?: Function;
204
}
205

206
// From Node.js 'http' module
207
interface IncomingMessage {
208
  headers: { [key: string]: string | string[] | undefined };
209
  method?: string;
210
  url?: string;
211
  statusCode?: number;
212
  httpVersion: string;
213
  socket: {
214
    remoteAddress?: string;
215
    remotePort?: number;
216
  };
217
}
218

219
interface ServerResponse {
220
  statusCode?: number; 
221
  statusMessage?: string;
222
  headers: { [key: string]: string | string[] | undefined };
223
  writeHead(statusCode: number, headers?: { [key: string]: string | string[] }): this;
224
  end(chunk?: any, encoding?: BufferEncoding, cb?: () => void): void;
225
}
226

227
interface ClientRequest {
228
  method?: string;
229
  path?: string;  
230
  host?: string;
231
  headers: { [key: string]: string | string[] | undefined };
232
  timeout?: number;
233
}
234

235
interface RequestOptions {
236
  hostname?: string;
237
  host?: string;
238
  port?: number;
239
  method?: string;
240
  path?: string;
241
  headers?: { [key: string]: string | string[] | undefined };
242
  timeout?: number;
243
}
244
```
245

246
### Core HTTP Types
247

248
```typescript { .api }
249
interface HttpInstrumentationConfig extends InstrumentationConfig {
250
  ignoreIncomingRequestHook?: IgnoreIncomingRequestFunction;
251
  ignoreOutgoingRequestHook?: IgnoreOutgoingRequestFunction;
252
  disableIncomingRequestInstrumentation?: boolean;
253
  disableOutgoingRequestInstrumentation?: boolean;
254
  applyCustomAttributesOnSpan?: HttpCustomAttributeFunction;
255
  requestHook?: HttpRequestCustomAttributeFunction;
256
  responseHook?: HttpResponseCustomAttributeFunction;
257
  startIncomingSpanHook?: StartIncomingSpanCustomAttributeFunction;
258
  startOutgoingSpanHook?: StartOutgoingSpanCustomAttributeFunction;
259
  serverName?: string;
260
  requireParentforOutgoingSpans?: boolean;
261
  requireParentforIncomingSpans?: boolean;
262
  headersToSpanAttributes?: {
263
    client?: { requestHeaders?: string[]; responseHeaders?: string[] };
264
    server?: { requestHeaders?: string[]; responseHeaders?: string[] };
265
  };
266
  enableSyntheticSourceDetection?: boolean;
267
  redactedQueryParams?: string[];
268
}
269

270
interface IgnoreIncomingRequestFunction {
271
  (request: IncomingMessage): boolean;
272
}
273

274
interface IgnoreOutgoingRequestFunction {
275
  (request: RequestOptions): boolean;
276
}
277

278
interface HttpCustomAttributeFunction {
279
  (
280
    span: Span,
281
    request: ClientRequest | IncomingMessage,
282
    response: IncomingMessage | ServerResponse
283
  ): void;
284
}
285

286
interface HttpRequestCustomAttributeFunction {
287
  (span: Span, request: ClientRequest | IncomingMessage): void;
288
}
289

290
interface HttpResponseCustomAttributeFunction {
291
  (span: Span, response: IncomingMessage | ServerResponse): void;
292
}
293

294
interface StartIncomingSpanCustomAttributeFunction {
295
  (request: IncomingMessage): Attributes;
296
}
297

298
interface StartOutgoingSpanCustomAttributeFunction {
299
  (request: RequestOptions): Attributes;
300
}
301
```