0
# HTTP Instrumentation
1

2
The HttpInstrumentation class is the main entry point for automatic HTTP telemetry collection in Node.js applications. It extends InstrumentationBase and provides automatic instrumentation for both `http` and `https` modules.
3

4
## Capabilities
5

6
### HttpInstrumentation Class
7

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

10
```typescript { .api }
11
/**
12
 * HTTP and HTTPS instrumentation for OpenTelemetry
13
 * Automatically instruments Node.js http and https modules to collect telemetry data
14
 */
15
class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
16
  /**
17
   * Creates a new HTTP instrumentation instance
18
   * @param config - Optional configuration for the instrumentation
19
   */
20
  constructor(config?: HttpInstrumentationConfig);
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
28
import { registerInstrumentations } from "@opentelemetry/instrumentation";
29

30
// Basic instantiation with default settings
31
const httpInstrumentation = new HttpInstrumentation();
32

33
// Registration with OpenTelemetry
34
registerInstrumentations({
35
  instrumentations: [httpInstrumentation],
36
});
37

38
// With configuration options
39
const configuredInstrumentation = new HttpInstrumentation({
40
  ignoreIncomingRequestHook: (req) => {
41
    // Ignore health check endpoints
42
    return req.url?.startsWith('/health') === true;
43
  },
44
  requestHook: (span, request) => {
45
    // Add custom attributes for every request
46
    span.setAttribute('custom.request_id', 
47
      request.headers['x-request-id'] || 'unknown');
48
  },
49
  headersToSpanAttributes: {
50
    server: {
51
      requestHeaders: ['user-agent', 'authorization'],
52
      responseHeaders: ['content-type']
53
    }
54
  }
55
});
56
```
57

58
### Inherited Methods
59

60
As an extension of InstrumentationBase, HttpInstrumentation inherits several important methods:
61

62
```typescript { .api }
63
/**
64
 * Enable the instrumentation
65
 */
66
enable(): void;
67

68
/**
69
 * Disable the instrumentation
70
 */
71
disable(): void;
72

73
/**
74
 * Set the instrumentation configuration (can be called after instantiation)
75
 * @param config - New configuration to apply
76
 */
77
setConfig(config: HttpInstrumentationConfig): void;
78

79
/**
80
 * Get the current configuration
81
 * @returns Current instrumentation configuration
82
 */
83
getConfig(): HttpInstrumentationConfig;
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
const httpInstrumentation = new HttpInstrumentation({
90
  disableOutgoingRequestInstrumentation: true
91
});
92

93
// Later in the application lifecycle
94
httpInstrumentation.setConfig({
95
  disableOutgoingRequestInstrumentation: false,
96
  ignoreOutgoingRequestHook: (req) => {
97
    // Now enable outgoing requests but ignore specific URLs
98
    return req.hostname?.includes('internal-service') === true;
99
  }
100
});
101

102
// Temporarily disable all HTTP instrumentation
103
httpInstrumentation.disable();
104

105
// Re-enable when needed
106
httpInstrumentation.enable();
107

108
// Check current configuration
109
const currentConfig = httpInstrumentation.getConfig();
110
console.log('Current server name:', currentConfig.serverName);
111
```
112

113
## Telemetry Data Collected
114

115
### Spans Created
116

117
The instrumentation automatically creates spans for:
118

119
- **Outgoing HTTP requests** (CLIENT spans): Created when your application makes HTTP requests to other services
120
- **Incoming HTTP requests** (SERVER spans): Created when your application receives HTTP requests
121

122
### Attributes Captured
123

124
Standard OpenTelemetry HTTP semantic convention attributes:
125

126
- `http.method` / `http.request.method` - HTTP request method (GET, POST, etc.)
127
- `http.url` / `url.full` - Full request URL  
128
- `http.status_code` / `http.response.status_code` - HTTP response status code
129
- `http.user_agent` / `user_agent.original` - User-Agent header value
130
- `net.peer.ip` / `client.address` - Client IP address
131
- `net.peer.port` / `client.port` - Client port number
132
- And many more based on semantic convention version
133

134
### Metrics Recorded
135

136
The instrumentation records HTTP duration metrics:
137

138
- `http.client.duration` - Duration of outgoing HTTP requests
139
- `http.server.duration` - Duration of incoming HTTP requests
140
- `http.client.request.duration` - Stable semantic convention client duration (when enabled)
141
- `http.server.request.duration` - Stable semantic convention server duration (when enabled)
142

143
## Semantic Convention Support
144

145
The instrumentation supports both old (v1.7.0) and new stable (v1.23.0+) HTTP semantic conventions:
146

147
```typescript
148
// Control via environment variable
149
process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http';      // Use stable only
150
process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http/dup';  // Use both old and stable
151
// Default: uses old v1.7.0 conventions
152
```
153

154
The instrumentation automatically adapts attribute names and metric names based on the configured semantic convention stability option.