What is the Performance Timeline API?

What is the Performance Timeline API?

The Performance Timeline is the browser's ordered record of performance entries for a page: navigation, resources, paint, layout shifts, your own marks and more. The W3C specification defines how entries are stored, read and observed, through getEntries(), getEntriesByType(), getEntriesByName() and PerformanceObserver. Other timing APIs write their entries into it.

How it works

Each global object, meaning each page or worker, keeps a buffer of entries per entry type. Every entry is a PerformanceEntry with name, entryType, startTime and duration. Two ways to read them:

• Snapshot: getEntries() returns what is in the timeline now, sorted by startTime, and getEntriesByType() and getEntriesByName() filter it. It never notifies you of new entries, and calling it twice returns the same entries again. Some types, such as layout shift, largest contentful paint, event and long task, are never returned by it.
• Observer: a PerformanceObserver calls you as entries are recorded. MDN calls this the preferred way. With type plus buffered: true you also receive entries recorded before you started observing.

The timeline is the shared layer. The Web Performance API is the wider family of interfaces that fill it, such as navigation timing and user timing. For server-side durations, see the Server-Timing API.

Entry types and buffer limits

MDN lists these entry types: element, event, first-input, largest-contentful-paint, layout-shift, longtask, mark, measure, navigation, paint, resource and visibility-state. Support varies by browser, so check PerformanceObserver.supportedEntryTypes before you observe. The list is usually shorter in workers.

The buffers are finite. MDN gives these limits per global object: 250 for resource (adjustable), 200 for longtask, 150 each for element, event, layout-shift and largest-contentful-paint, 50 for visibility-state, 2 for paint, 1 for first-input, and no limit for mark, measure and navigation. When a buffer is full, new entries are not stored and a dropped-entries count goes up, which an observer receives as droppedEntriesCount.

Example

// which entry types does this browser support?
console.log(PerformanceObserver.supportedEntryTypes);

// resource entries, including those recorded before this line
const po = new PerformanceObserver((list, obs, opts) => {
  for (const e of list.getEntries()) console.log(e.entryType, e.name, e.startTime);
  if (opts && opts.droppedEntriesCount) console.warn("dropped:", opts.droppedEntriesCount);
});
po.observe({ type: "resource", buffered: true });

// snapshot of what is in the timeline right now, ordered by startTime
const marks = performance.getEntriesByType("mark");

A page with a lot of images and scripts can exceed 250 resource entries. Raise the limit with performance.setResourceTimingBufferSize(), or save and clear entries with clearResourceTimings() when the resourcetimingbufferfull event fires.

Common mistakes

• Polling getEntries(). You re-read old entries and still miss some types. Use an observer.
• Mixing options. entryTypes cannot be combined with type or buffered, and buffered works only with type. To buffer several types, create one observer per type.
• Ignoring buffer limits. On a busy page, late resource entries can be silently missing.
• Treating one visit as the truth. The timeline describes one user, one device and one network. Aggregate many visits.
• Assuming it feeds your monitoring by itself. The browser only records. You still have to send, store and alert on the numbers.

Performance Timeline, testing and monitoring

The timeline is where real user monitoring gets raw data, including the signals behind Core Web Vitals. It tells you what visitors experienced, but not what happens when nobody is visiting. LoadFocus page speed monitoring complements it with scheduled Lighthouse audits from cloud regions, history and alerts. For a step-by-step setup, read how to monitor Core Web Vitals with alerts and reports.

FAQ

What is the difference between the Performance Timeline and the Performance API?

The timeline is the ordered record of entries and the rules for reading and observing it. The Performance API is the broader set of interfaces that produce entries, such as navigation, resource and user timing.

Should I use getEntries() or PerformanceObserver?

Prefer PerformanceObserver. It is notified as entries arrive and, with type and buffered, also returns earlier ones. getEntries() is a snapshot and cannot return some types at all.

Why are entries missing on a busy page?

Buffers have size limits, for example 250 for resource entries. Once full, new entries are dropped. Raise the limit or clear the buffer after saving what you need.

Does the Performance Timeline work in web workers?

Yes. The interfaces are exposed in workers too, though the list of supported entry types is typically shorter there.