0
# Reporting Observer
1

2
Browser-only integration that captures Reporting API events such as crash reports, deprecation warnings, and intervention reports. This integration helps monitor browser-generated reports about web application issues.
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Reporting API integration for capturing browser reports
11
 * @param options - Configuration for report types to observe
12
 * @returns Integration instance that monitors Reporting API
13
 */
14
function reportingObserverIntegration(options?: ReportingObserverOptions): Integration;
15

16
interface ReportingObserverOptions {
17
  /** Types of reports to observe */
18
  types?: ReportTypes[];
19
}
20

21
type ReportTypes = 'crash' | 'deprecation' | 'intervention';
22
```
23

24
### Legacy Class-based Integration (Deprecated)
25

26
```typescript { .api }
27
/**
28
 * Legacy class-based Reporting Observer integration
29
 * @deprecated Use reportingObserverIntegration() instead
30
 */
31
class ReportingObserver implements Integration {
32
  constructor(options?: {
33
    types?: ReportTypes[];
34
  });
35
  name: string;
36
  setupOnce(): void;
37
  setup(client: Client): void;
38
}
39
```
40

41
## Report Types
42

43
### Crash Reports
44

45
Generated when the browser detects application crashes:
46
- **Type**: `'crash'`
47
- **Content**: Crash ID and reason information
48
- **Usefulness**: Identify browser-level crashes affecting users
49

50
### Deprecation Reports
51

52
Generated when deprecated web features are used:
53
- **Type**: `'deprecation'`
54
- **Content**: Deprecated feature ID, removal timeline, usage location
55
- **Usefulness**: Identify code using deprecated APIs before they're removed
56

57
### Intervention Reports
58

59
Generated when browser intervenes to improve user experience:
60
- **Type**: `'intervention'`
61
- **Content**: Intervention reason and affected feature
62
- **Usefulness**: Identify performance or UX issues the browser is addressing
63

64
## Configuration Options
65

66
### types Option
67

68
Array of report types to observe:
69
- **Default**: `['crash', 'deprecation', 'intervention']` (all types)
70
- **Selective**: `['crash', 'deprecation']` (exclude interventions)
71
- **Specific**: `['crash']` (only crash reports)
72

73
## Browser Support
74

75
This integration requires:
76
- **Reporting API support**: Modern browsers (Chrome 69+, Firefox 65+)
77
- **Browser environment**: Does not work in Node.js or server-side rendering
78
- **Automatic detection**: Gracefully skips setup if Reporting API unavailable
79

80
## Report Structure Types
81

82
```typescript { .api }
83
interface Report {
84
  [key: string]: unknown;
85
  type: ReportTypes;
86
  url: string;
87
  body?: ReportBody;
88
}
89

90
type ReportBody = CrashReportBody | DeprecationReportBody | InterventionReportBody;
91

92
interface CrashReportBody {
93
  [key: string]: unknown;
94
  crashId: string;
95
  reason?: string;
96
}
97

98
interface DeprecationReportBody {
99
  [key: string]: unknown;
100
  id: string;
101
  anticipatedRemoval?: Date;
102
  message: string;
103
  sourceFile?: string;
104
  lineNumber?: number;
105
  columnNumber?: number;
106
}
107

108
interface InterventionReportBody {
109
  [key: string]: unknown;
110
  id: string;
111
  message: string;
112
  sourceFile?: string;
113
  lineNumber?: number;
114
  columnNumber?: number;
115
}
116
```
117

118
## Usage Examples
119

120
```typescript
121
import { reportingObserverIntegration } from '@sentry/integrations';
122
import * as Sentry from '@sentry/browser';
123

124
// Monitor all report types (default)
125
Sentry.init({
126
  dsn: 'YOUR_DSN',
127
  integrations: [
128
    reportingObserverIntegration()
129
  ]
130
});
131

132
// Monitor only crashes and deprecations
133
Sentry.init({
134
  dsn: 'YOUR_DSN',
135
  integrations: [
136
    reportingObserverIntegration({
137
      types: ['crash', 'deprecation']
138
    })
139
  ]
140
});
141

142
// Monitor only crash reports
143
Sentry.init({
144
  dsn: 'YOUR_DSN',
145
  integrations: [
146
    reportingObserverIntegration({
147
      types: ['crash']
148
    })
149
  ]
150
});
151
```
152

153
## Event Generation
154

155
Reports are converted to Sentry message events with:
156

157
**Event Message Format**: `ReportingObserver [type]: details`
158
- Crash: `ReportingObserver [crash]: crashId reason`
159
- Deprecation: `ReportingObserver [deprecation]: message`
160
- Intervention: `ReportingObserver [intervention]: message`
161

162
**Event Context**:
163
- `extra.url`: URL where report was generated
164
- `extra.body`: Complete report body object
165

166
## Real-world Examples
167

168
### Deprecation Warning
169

170
```javascript
171
// Using deprecated feature triggers report:
172
document.write('<p>This is deprecated</p>');
173

174
// Results in Sentry event:
175
// "ReportingObserver [deprecation]: Use of document.write() is deprecated"
176
```
177

178
### Browser Intervention
179

180
```javascript
181
// Slow script triggers intervention:
182
while(true) { /* infinite loop */ }
183

184
// Results in Sentry event:
185
// "ReportingObserver [intervention]: Long running script was terminated"
186
```
187

188
### Crash Report
189

190
```javascript
191
// Browser crash (simplified example):
192
// Results in Sentry event:
193
// "ReportingObserver [crash]: 12345 Out of memory"
194
```
195

196
## Integration Benefits
197

198
1. **Proactive Monitoring**: Catch browser-level issues before users report them
199
2. **Deprecation Tracking**: Stay ahead of breaking API changes
200
3. **Performance Insights**: Understand when browsers intervene for performance
201
4. **Crash Visibility**: Get notified of browser crashes affecting your application
202

203
This integration is particularly valuable for modern web applications that need to stay current with browser changes and maintain optimal performance.