ReportingObserver

ReportingObserver is the in-page side of the Reporting API. Instead of sending reports to a server, it hands them to JavaScript on the same page, so you can log deprecations, interventions, and policy violations from the client. It also exposes a buffer of reports generated before the observer started.

What it observes

A ReportingObserver sees the report types the browser surfaces to the page: deprecation, intervention, and csp-violation, plus, where the browser supports them, coep, permissions-policy-violation, and integrity-violation. You can observe all of them or filter to specific types.

It does not surface every report type. crash reports never reach a ReportingObserver, since the page is gone before a callback could run, so a crash is delivered to a server endpoint only. csp-hash reports are likewise server-endpoint only. For crash reporting, and for any aggregation across users, use a server endpoint instead.

Basic usage

You construct an observer with a callback and options, then call observe().

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    console.log(report.type, report.body);
  }
}, { types: ["deprecation"], buffered: true });

observer.observe();

The constructor takes (callback, options). In options, types is an array of report types to watch (omit it to observe all observable types), and buffered: true delivers reports that were generated before observe() was called, from the browser's report buffer, which is how you catch deprecations that fired during early page load. The observer also has disconnect() to stop, and takeRecords() to pull and clear any queued reports synchronously. ReportingObserver is available in Web Workers as well as documents.

When to use it vs a server endpoint

Use ReportingObserver when you want reports in your own client code: surfacing deprecations to developers in a staging build, or feeding violations into a front-end error pipeline you already run. Use a server endpoint (the rest of this reference) when you need crash reports, or when you want to aggregate reports across all your users rather than per-session. CentralCSP collects the out-of-band, server-side stream, which is the one you build monitoring and alerting on.

Browser support

ReportingObserver is available across current browsers, after shipping in Chromium first. Support is not uniform per report type: observing deprecation is the most broadly available, and the API only ever surfaces some of the report types the Reporting API defines (deprecation, intervention, and csp-violation, with coep, permissions-policy-violation, and integrity-violation where supported). Crash reports are not among them; they are delivered to a server endpoint only. Confirm the specific types you depend on before relying on the API in production.

See also

• How the Reporting API works
• Deprecation report
• Intervention report
• ReportingObserver in JavaScript, a practical guide

Sources

• MDN, ReportingObserver
• W3C, Reporting API