0
# HTTP Client Monitoring
1

2
Monitors HTTP requests made via fetch API and XMLHttpRequest, creating Sentry events for failed requests based on configurable status codes and URL patterns. Useful for tracking API failures and network issues.
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Creates events for failed client-side HTTP requests
11
 * @param options - Configuration for HTTP monitoring
12
 * @returns Integration instance that monitors HTTP requests
13
 */
14
function httpClientIntegration(options?: Partial<HttpClientOptions>): Integration;
15

16
interface HttpClientOptions {
17
  /** HTTP status codes that should be considered failed */
18
  failedRequestStatusCodes: HttpStatusCodeRange[];
19
  /** Targets to track for failed requests */
20
  failedRequestTargets: HttpRequestTarget[];
21
}
22

23
type HttpStatusCodeRange = [number, number] | number;
24
type HttpRequestTarget = string | RegExp;
25
```
26

27
### Legacy Class-based Integration (Deprecated)
28

29
```typescript { .api }
30
/**
31
 * Legacy class-based HTTP client integration
32
 * @deprecated Use httpClientIntegration() instead
33
 */
34
class HttpClient implements Integration {
35
  constructor(options?: {
36
    failedRequestStatusCodes: HttpStatusCodeRange[];
37
    failedRequestTargets: HttpRequestTarget[];
38
  });
39
  name: string;
40
  setup(client: Client): void;
41
}
42
```
43

44
## Configuration Options
45

46
### failedRequestStatusCodes
47

48
Defines which HTTP status codes should trigger events:
49

50
- **Default**: `[[500, 599]]` (server errors only)
51
- **Single codes**: `[404, 500]`
52
- **Ranges**: `[[400, 499], [500, 599]]` (client and server errors)
53
- **Mixed**: `[[500, 505], 507, 510]`
54

55
### failedRequestTargets
56

57
Defines which URLs to monitor:
58

59
- **Default**: `[/.*/]` (all URLs)
60
- **String matching**: `['http://api.example.com', '/api/']`
61
- **Regex patterns**: `[/\/api\/.*/, /admin/]`
62
- **Combined**: `['localhost', /\/api\/v[12]\//]`
63

64
## Behavior
65

66
### Request Monitoring
67

68
The integration instruments both fetch API and XMLHttpRequest:
69

70
- **Fetch API**: Uses `addFetchInstrumentationHandler()` 
71
- **XMLHttpRequest**: Uses `addXhrInstrumentationHandler()`
72
- **Automatic**: No manual wrapping required
73

74
### Event Creation
75

76
Failed requests generate synthetic error events containing:
77

78
**Request Information**:
79
- URL, HTTP method
80
- Request headers (if `sendDefaultPii` enabled)
81
- Request cookies (if `sendDefaultPii` enabled)
82

83
**Response Information**:
84
- Status code, response headers
85
- Response cookies, response body size
86
- Exception mechanism: `{ type: 'http.client', handled: false }`
87

88
### Privacy Controls
89

90
Personal data inclusion is controlled by Sentry client's `sendDefaultPii` option:
91
- **true**: Includes headers and cookies in events
92
- **false**: Excludes headers and cookies for privacy
93

94
## Usage Examples
95

96
```typescript
97
import { httpClientIntegration } from '@sentry/integrations';
98
import * as Sentry from '@sentry/browser';
99

100
// Monitor server errors only (default)
101
Sentry.init({
102
  dsn: 'YOUR_DSN',
103
  integrations: [
104
    httpClientIntegration()
105
  ]
106
});
107

108
// Monitor both client and server errors
109
Sentry.init({
110
  dsn: 'YOUR_DSN',
111
  integrations: [
112
    httpClientIntegration({
113
      failedRequestStatusCodes: [[400, 599]]
114
    })
115
  ]
116
});
117

118
// Monitor specific APIs and error codes
119
Sentry.init({
120
  dsn: 'YOUR_DSN',
121
  integrations: [
122
    httpClientIntegration({
123
      failedRequestStatusCodes: [404, [500, 599]],
124
      failedRequestTargets: [
125
        'https://api.example.com',
126
        /\/api\/v[12]\//,
127
        'localhost:3000'
128
      ]
129
    })
130
  ]
131
});
132

133
// Include headers and cookies in events
134
Sentry.init({
135
  dsn: 'YOUR_DSN',
136
  sendDefaultPii: true,  // Enables header/cookie capture
137
  integrations: [
138
    httpClientIntegration({
139
      failedRequestStatusCodes: [[400, 499], [500, 599]]
140
    })
141
  ]
142
});
143
```
144

145
## Event Structure
146

147
Generated events have the following structure:
148

149
```typescript
150
{
151
  message: "HTTP Client Error with status code: 404",
152
  exception: {
153
    values: [{
154
      type: "Error",
155
      value: "HTTP Client Error with status code: 404"
156
    }]
157
  },
158
  request: {
159
    url: "https://api.example.com/users/123",
160
    method: "GET",
161
    headers: { /* if sendDefaultPii enabled */ },
162
    cookies: { /* if sendDefaultPii enabled */ }
163
  },
164
  contexts: {
165
    response: {
166
      status_code: 404,
167
      headers: { /* if sendDefaultPii enabled */ },
168
      cookies: { /* if sendDefaultPii enabled */ },
169
      body_size: 1234  // from Content-Length header
170
    }
171
  }
172
}
173
```
174

175
## Filtering
176

177
The integration automatically filters out:
178
- **Sentry requests**: Prevents infinite loops by excluding Sentry API calls
179
- **Non-matching status codes**: Only configured status codes generate events
180
- **Non-matching URLs**: Only URLs matching target patterns generate events
181

182
This integration is particularly useful for SPAs and applications that make many API calls, providing visibility into client-side network failures.