PerformanceObserver API
Slap yourself if
You think PerformanceObserver is just window.performance with callbacks.
Why this exists
PerformanceObserver exists because modern performance signals are asynchronous, buffered, and emitted after the fact. Pulling metrics synchronously misses data, biases results, and collapses under real user conditions.
Mental model
PerformanceObserver is a stream of performance events, not a snapshot API. You subscribe to what the browser already decided to measure — on its schedule, with its buffering rules.
- The browser records performance entries internally as work happens.
- Entries are buffered by type with implementation-defined limits.
- PerformanceObserver subscribes to entry streams asynchronously.
- Delivery timing depends on buffering, page lifecycle, and visibility.
- Observing too late and missing early entries.
- Assuming all entries are delivered immediately.
- Mixing pull-based and observer-based metrics incorrectly.
- Treating metrics as precise timestamps instead of signals.
PerformanceObserver provides asynchronous access to buffered performance entry streams, allowing code to observe metrics like paint, layout shifts, and long tasks without relying on synchronous polling.
- Registering observers after page load
- Assuming zero entries means zero issues
- Reading metrics without understanding buffering limits
- Using metrics without correlating user visibility
Deep dive
Requires Pro
Premium deep dives include more internals, more scars.