An analytics module creates a PerformanceObserver for the 'largest-contentful-paint' entry type, but on fast page loads its callback never fires. Which observe() option was most likely omitted, and what does that option do?

## The timeline and the observer are two different things The browser maintains a *performance timeline*: an ordered buffer of `PerformanceEntry` objects it fills in as things happen — the navigation, each resource, paint milestones, layout shifts, the largest contentful paint candidate, long tasks, and any marks and measures your code adds. That buffer exists from the moment the document starts, regardless of whether anyone is watching. `PerformanceObserver` is a *subscription* to future additions to that buffer. `new PerformanceObserver(callback)` then `observer.observe({...})` registers interest; from that point on the browser batches matching new entries and invokes your callback with a `PerformanceObserverEntryList`. Entries recorded *before* `observe()` ran are not delivered — the subscription starts when you subscribe. ## Why that breaks metric collection specifically Metric entries are recorded early and are recorded once. On a well-optimised page the largest contentful paint may occur at 800 ms; a deferred analytics bundle might not evaluate until 1200 ms. The entry exists, sitting in the timeline, but the observer registered after it and hears nothing. The failure is silent — no error, no entry, and it correlates with fast loads, which is exactly the wrong bias to introduce into your data. Same story for `first-contentful-paint` (a `paint` entry), early `layout-shift` entries during initial render, `navigation`, and any `resource` entries for assets fetched before your script ran. ## What buffered: true does ```javascript const observer = new PerformanceObserver((list) => { for (const entry of list.getEntries()) { report(entry); } }); observer.observe({ type: 'largest-contentful-paint', buffered: true }); ``` With `buffered: true`, the browser queues the already-buffered matching entries and delivers them in the observer's first callback, then continues with live delivery. From your callback's point of view there is no difference between a replayed entry and a live one; ordering by `startTime` is preserved. ## The type vs entryTypes trap `observe()` accepts two mutually exclusive shapes: - `observe({ type: 'layout-shift', buffered: true })` — a single entry type, and the only form where `buffered` is meaningful. - `observe({ entryTypes: ['mark', 'measure'] })` — several types at once, and `buffered` is **ignored** here. Passing both `type` and `entryTypes` in one call throws a `TypeError`. And an observer that has been used with `type` cannot later be switched to `entryTypes` (or vice versa) — that raises an error too. In practice this pushes you to one observer per entry type, which is also what you want, because different metrics need different finalisation logic anyway. The reason the plural form ignores `buffered` is worth internalising: `entryTypes` was the original API shape and predates buffering, and it is the shape people reach for when they want "everything", which is exactly when they most often get bitten. ## Buffer limits The replay is only as good as what the browser kept. Each entry type has a buffer size limit; the resource timing buffer in particular defaults to 250 entries, after which new resource entries are dropped and a `resourcetimingbufferfull` event fires on `performance`. On an asset-heavy page that is easy to hit before your script runs. You can raise it with `performance.setResourceTimingBufferSize(n)` or drain it with `performance.clearResourceTimings()`, but the honest fix is to register the observer as early as possible — inline, in the document head, before the rest of the bundle. ## Feature detection Not every browser supports every entry type, and observing an unsupported type is a no-op at best. The static list is the safe check: ```javascript if (PerformanceObserver.supportedEntryTypes.includes('layout-shift')) { // safe to observe } ``` Wrapping `observe()` in a `try/catch` is also common, because older implementations throw for unknown types rather than ignoring them. ## The takeaway for instrumentation code Three rules follow. Register performance observers as early in the document as you can — an inline snippet beats a deferred bundle. Always use the `type` + `buffered: true` form for anything that can happen before your code runs. And never conclude from an empty dataset that the page had no layout shifts or no LCP; conclude first that your observer started too late.