PerformanceObserver

PerformanceObserver
Name	PerformanceObserver
Introduced	Navigation Timing Level 2
Standard	World Wide Web Consortium Web Performance Working Group
Api	Web APIs
Language	JavaScript

PerformanceObserver

PerformanceObserver is a web platform API defined by the World Wide Web Consortium and implemented across major browsers to observe web page performance entry events such as Navigation Timing, Resource Timing, and Long Tasks. It enables developers working with Google Chrome, Mozilla Firefox, Microsoft Edge, Apple Safari, and server-side runtimes like Node.js to collect fine-grained timing data for Web Performance Optimization and integration with tools like Lighthouse, PageSpeed Insights, and WebPageTest. The API complements other standards authored by the Web Performance Working Group and used in performance monitoring services such as New Relic, Datadog, and Sentry.

Overview

PerformanceObserver provides a callback-based mechanism to receive PerformanceEntry objects emitted by the browser's timing subsystems, including entries from Navigation Timing, Paint Timing, Resource Timing, and User Timing. Designed to work with the Performance Timeline specification, it supports observing both historical entries and new entries as they occur, enabling integration with analytics pipelines like Google Analytics and observability platforms including Prometheus exporters or Elastic Stack ingestion. The API is part of the broader Web Performance API family and interacts with features standardized or discussed in contexts such as WHATWG and W3C meetings.

Usage and Syntax

A PerformanceObserver is constructed with a callback that receives an array-like list of PerformanceEntry instances and an observer object; the observer is then configured via observe(options) where options specify types and buffering via entryTypes and buffered. Typical usage patterns are found in developer guidance from Mozilla Developer Network and examples in Chromium developer resources. The lifecycle includes creating the observer, calling observe, handling the callback to process entries, and optionally calling disconnect() to stop observation or takeRecords() to retrieve queued entries. Integration details often reference interoperability notes from Can I use and guidance from WHATWG drafts.

Observed Entry Types

The observer supports multiple entryType values standardized across specifications and implementations, including: - Navigation Timing entries like navigationStart and unloadEventEnd. - Paint Timing entries such as first-paint and first-contentful-paint. - Resource Timing entries for HTTP resource fetches and timing of scripts, images, and stylesheets loaded from origins like Content Delivery Network endpoints. - Long Tasks representing main-thread work exceeding a threshold, useful alongside Task Scheduling heuristics. - User Timing marks and measures created via performance.mark and performance.measure. Some entry types derive from proposals or donor specs discussed in working groups at W3C and implementations tracked in Chromium Bug Tracker and Mozilla Bugzilla.

Examples and Code Samples

Basic observer creation follows patterns demonstrated in Mozilla Developer Network examples and Chromium blogs: var observer = new PerformanceObserver(function(list, obs) { list.getEntries().forEach(function(entry) { console.log(entry.name, entry.startTime, entry.duration); }); }); observer.observe({ entryTypes: ['paint', 'resource'] });

For measuring custom instrumentation with User Timing: performance.mark('startTask'); /* work */ performance.mark('endTask'); performance.measure('taskDuration', 'startTask', 'endTask');

Then observe user timing entries and forward them to analytics providers such as Google Analytics or monitoring platforms like New Relic and Datadog. When integrating with Lighthouse workflows, ensure buffering by using observe({ entryTypes: ['measure'], buffered: true }). Server-side replay or synthetic testing via WebPageTest or Puppeteer scripts can capture observer output during test runs.

Performance and Limitations

Although PerformanceObserver aims to be low-overhead, collectors must be cautious: processing many high-frequency entries (for example, many Resource Timing records on heavy pages) can add CPU and memory pressure impacting metrics like First Contentful Paint and Largest Contentful Paint. Browsers implement caps and pruning strategies; entry buffering behavior varies across Google Chrome, Mozilla Firefox, and Apple Safari and may drop entries when memory thresholds are exceeded. Privacy and cross-origin rules apply: resource timing for cross-origin requests can be reduced without explicit timing-allow-origin headers set by origins like those using Content Delivery Network services. Security considerations and same-origin policies referenced in W3C discussions affect available granularity.

Browser Support and Compatibility

Support for PerformanceObserver and specific entryTypes differs by browser and version. Google Chrome and Chromium-based Microsoft Edge tend to implement new entry types earlier, while Mozilla Firefox and Apple Safari may lag or implement with different semantics. Compatibility tables and feature detection strategies are documented by Can I use and Mozilla Developer Network; polyfills or feature-gated fallbacks are sometimes provided by libraries maintained by organizations like OpenJS Foundation projects. When targeting a range of environments including Node.js and mobile browsers on Android or iOS, test behavior in real-world scenarios and consult browser-specific bug trackers such as Chromium Bug Tracker and Mozilla Bugzilla for known issues.

Category:Web APIs