0
# Configuration
1

2
The HttpInstrumentationConfig interface provides extensive options for customizing HTTP instrumentation behavior, including request filtering, custom attributes, header capture, and telemetry control.
3

4
## Capabilities
5

6
### HttpInstrumentationConfig Interface
7

8
Main configuration interface for HTTP instrumentation with comprehensive options for customizing telemetry collection behavior.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for HTTP instrumentation
13
 * Extends the base InstrumentationConfig with HTTP-specific options
14
 */
15
interface HttpInstrumentationConfig extends InstrumentationConfig {
16
  /** Function to filter incoming requests from instrumentation */
17
  ignoreIncomingRequestHook?: IgnoreIncomingRequestFunction;
18
  /** Function to filter outgoing requests from instrumentation */
19
  ignoreOutgoingRequestHook?: IgnoreOutgoingRequestFunction;
20
  /** Completely disable incoming request instrumentation */
21
  disableIncomingRequestInstrumentation?: boolean;
22
  /** Completely disable outgoing request instrumentation */
23
  disableOutgoingRequestInstrumentation?: boolean;
24
  /** Function for adding custom attributes after response is handled */
25
  applyCustomAttributesOnSpan?: HttpCustomAttributeFunction;
26
  /** Function for adding custom attributes before request is handled */
27
  requestHook?: HttpRequestCustomAttributeFunction;
28
  /** Function for adding custom attributes before response is handled */
29
  responseHook?: HttpResponseCustomAttributeFunction;
30
  /** Function for adding custom attributes before incoming span is started */
31
  startIncomingSpanHook?: StartIncomingSpanCustomAttributeFunction;
32
  /** Function for adding custom attributes before outgoing span is started */
33
  startOutgoingSpanHook?: StartOutgoingSpanCustomAttributeFunction;
34
  /** Primary server name for virtual host matching */
35
  serverName?: string;
36
  /** Require parent span to create spans for outgoing requests */
37
  requireParentforOutgoingSpans?: boolean;
38
  /** Require parent span to create spans for incoming requests */
39
  requireParentforIncomingSpans?: boolean;
40
  /** Map HTTP headers to span attributes */
41
  headersToSpanAttributes?: {
42
    client?: { requestHeaders?: string[]; responseHeaders?: string[] };
43
    server?: { requestHeaders?: string[]; responseHeaders?: string[] };
44
  };
45
  /** Enable automatic population of synthetic source type (experimental) */
46
  enableSyntheticSourceDetection?: boolean;
47
  /** Additional query parameters to redact (experimental) */
48
  redactedQueryParams?: string[];
49
}
50
```
51

52
## Configuration Options
53

54
### Request Filtering Options
55

56
Control which requests are instrumented:
57

58
```typescript { .api }
59
/** Completely disable incoming request instrumentation */
60
disableIncomingRequestInstrumentation?: boolean;
61

62
/** Completely disable outgoing request instrumentation */
63
disableOutgoingRequestInstrumentation?: boolean;
64

65
/** Function to filter incoming requests from instrumentation */
66
ignoreIncomingRequestHook?: IgnoreIncomingRequestFunction;
67

68
/** Function to filter outgoing requests from instrumentation */
69
ignoreOutgoingRequestHook?: IgnoreOutgoingRequestFunction;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
76

77
const instrumentation = new HttpInstrumentation({
78
  // Don't instrument any incoming requests (useful for client-only apps)
79
  disableIncomingRequestInstrumentation: true,
80
  
81
  // Filter outgoing requests to ignore internal services
82
  ignoreOutgoingRequestHook: (req) => {
83
    const hostname = req.hostname || req.host;
84
    return hostname?.includes('internal.company.com') === true;
85
  },
86
  
87
  // Filter incoming requests to ignore health checks and static assets
88
  ignoreIncomingRequestHook: (req) => {
89
    const url = req.url || '';
90
    return url.startsWith('/health') || 
91
           url.startsWith('/static/') || 
92
           url.endsWith('.ico');
93
  }
94
});
95
```
96

97
### Custom Attribute Options
98

99
Add custom attributes to spans at different lifecycle points:
100

101
```typescript { .api }
102
/** Function for adding custom attributes after response is handled */
103
applyCustomAttributesOnSpan?: HttpCustomAttributeFunction;
104

105
/** Function for adding custom attributes before request is handled */
106
requestHook?: HttpRequestCustomAttributeFunction;
107

108
/** Function for adding custom attributes before response is handled */
109
responseHook?: HttpResponseCustomAttributeFunction;
110

111
/** Function for adding custom attributes before incoming span is started */
112
startIncomingSpanHook?: StartIncomingSpanCustomAttributeFunction;
113

114
/** Function for adding custom attributes before outgoing span is started */
115
startOutgoingSpanHook?: StartOutgoingSpanCustomAttributeFunction;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
const instrumentation = new HttpInstrumentation({
122
  // Add attributes at span start for incoming requests
123
  startIncomingSpanHook: (request) => {
124
    return {
125
      'custom.request_id': request.headers['x-request-id'],
126
      'custom.tenant_id': request.headers['x-tenant-id'],
127
      'custom.api_version': request.headers['api-version'] || 'v1'
128
    };
129
  },
130
  
131
  // Add attributes during request processing
132
  requestHook: (span, request) => {
133
    const userAgent = request.headers['user-agent'];
134
    if (userAgent) {
135
      span.setAttribute('custom.user_agent', userAgent);
136
      span.setAttribute('custom.is_mobile', userAgent.includes('Mobile'));
137
    }
138
  },
139
  
140
  // Add attributes during response processing
141
  responseHook: (span, response) => {
142
    span.setAttribute('custom.response_size', 
143
      response.headers['content-length'] || '0');
144
    span.setAttribute('custom.cache_hit', 
145
      response.headers['x-cache'] === 'HIT');
146
  },
147
  
148
  // Add comprehensive attributes after request completion
149
  applyCustomAttributesOnSpan: (span, request, response) => {
150
    // Calculate and add request duration in a custom format
151
    const duration = Date.now() - span.startTime[0] * 1000;
152
    span.setAttribute('custom.duration_category', 
153
      duration < 100 ? 'fast' : duration < 500 ? 'medium' : 'slow');
154
  }
155
});
156
```
157

158
### Header Capture Options
159

160
Configure which HTTP headers to capture as span attributes:
161

162
```typescript { .api }
163
/** Map HTTP headers to span attributes */
164
headersToSpanAttributes?: {
165
  client?: { requestHeaders?: string[]; responseHeaders?: string[] };
166
  server?: { requestHeaders?: string[]; responseHeaders?: string[] };
167
};
168
```
169

170
**Usage Examples:**
171

172
```typescript
173
const instrumentation = new HttpInstrumentation({
174
  headersToSpanAttributes: {
175
    // For client requests (outgoing)
176
    client: {
177
      requestHeaders: [
178
        'authorization',    // Capture auth headers (be careful with sensitive data)
179
        'content-type',
180
        'accept',
181
        'x-api-key'
182
      ],
183
      responseHeaders: [
184
        'content-type',
185
        'server',
186
        'x-response-time',
187
        'x-rate-limit-remaining'
188
      ]
189
    },
190
    // For server requests (incoming)
191
    server: {
192
      requestHeaders: [
193
        'user-agent',
194
        'referer',
195
        'accept-language',
196
        'x-forwarded-for'
197
      ],
198
      responseHeaders: [
199
        'content-type',
200
        'cache-control',
201
        'x-custom-header'
202
      ]
203
    }
204
  }
205
});
206
```
207

208
### Parent Span Requirements
209

210
Control whether spans require parent spans to be created:
211

212
```typescript { .api }
213
/** Require parent span to create spans for outgoing requests */
214
requireParentforOutgoingSpans?: boolean;
215

216
/** Require parent span to create spans for incoming requests */
217
requireParentforIncomingSpans?: boolean;
218
```
219

220
**Usage Examples:**
221

222
```typescript
223
const instrumentation = new HttpInstrumentation({
224
  // Only create outgoing request spans when there's already an active span
225
  // Useful to avoid creating orphaned spans for background tasks
226
  requireParentforOutgoingSpans: true,
227
  
228
  // Only create incoming request spans when there's distributed tracing context
229
  // Useful in microservice environments to avoid root spans
230
  requireParentforIncomingSpans: true
231
});
232
```
233

234
### Server Configuration
235

236
Set server identification for span attributes:
237

238
```typescript { .api }
239
/** Primary server name for virtual host matching */
240
serverName?: string;
241
```
242

243
**Usage Examples:**
244

245
```typescript
246
const instrumentation = new HttpInstrumentation({
247
  // Set the server name for span attributes
248
  serverName: 'api.mycompany.com'
249
});
250
```
251

252
### Experimental Features
253

254
Configure experimental features (subject to change):
255

256
```typescript { .api }
257
/** Enable automatic population of synthetic source type (experimental) */
258
enableSyntheticSourceDetection?: boolean;
259

260
/** Additional query parameters to redact (experimental) */
261
redactedQueryParams?: string[];
262
```
263

264
**Usage Examples:**
265

266
```typescript
267
const instrumentation = new HttpInstrumentation({
268
  // Enable synthetic traffic detection (bots, test tools)
269
  enableSyntheticSourceDetection: true,
270
  
271
  // Redact sensitive query parameters
272
  redactedQueryParams: [
273
    'api_key',
274
    'secret',
275
    'password',
276
    'token',
277
    'auth',
278
    'signature'
279
  ]
280
});
281
```
282

283
## Complete Configuration Example
284

285
```typescript
286
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
287

288
const comprehensiveConfig = new HttpInstrumentation({
289
  // Basic filtering
290
  ignoreIncomingRequestHook: (req) => {
291
    return req.url?.includes('/health') === true;
292
  },
293
  ignoreOutgoingRequestHook: (req) => {
294
    return req.hostname?.includes('localhost') === true;
295
  },
296
  
297
  // Custom attributes
298
  requestHook: (span, request) => {
299
    span.setAttribute('service.component', 'http-client');
300
  },
301
  
302
  // Header capture
303
  headersToSpanAttributes: {
304
    client: {
305
      requestHeaders: ['content-type'],
306
      responseHeaders: ['server']
307
    },
308
    server: {
309
      requestHeaders: ['user-agent'],
310
      responseHeaders: ['content-type']
311
    }
312
  },
313
  
314
  // Span requirements
315
  requireParentforOutgoingSpans: true,
316
  
317
  // Server identification
318
  serverName: 'my-service',
319
  
320
  // Experimental features
321
  enableSyntheticSourceDetection: true,
322
  redactedQueryParams: ['api_key', 'token']
323
});
324
```