Field Performance Observation and Sample Contracts

A performance entry is an observation made by a browser, not a complete account of a user's task. Navigation, resource, paint, and custom marks describe different clocks and phases. Some entry types are unavailable in a given browser; some useful early entries arrive before application instrumentation starts. Collection must check support, request buffered entries when supported, and define exactly which event belongs to a page view. Field data should be grouped by route class, device class, and release rather than treated as one universal number. A fast median can conceal a painful tail. Conversely, a small slow sample can reflect a particular network or device rather than a widespread regression. Keep a stable definition of the denominator and track missing measurements as a first-class signal.

Working case

An inspection portal records load duration only after its application bundle executes. The first paint has already happened, so the dashboard silently excludes early navigation work. A new map page appears fast in the aggregate because its visitors mostly use desktop computers, while field inspectors on modest phones wait for a late route chunk. Team 47 first compares device and route cohorts, then records whether each entry type exists and whether the observer saw buffered entries. The report shows sample size and missingness beside each percentile. An address, case identifier, and full asset URL are omitted from the event payload; route class and coarse connection context are enough to locate the regression.

Implementation boundary

function eligibleTimingTypes(supportedTypes, requestedTypes) {
  const supported = new Set(supportedTypes);
  return requestedTypes.filter((entryType) => supported.has(entryType));
}
console.log(eligibleTimingTypes(["navigation", "paint"], ["paint", "resource", "navigation"]).join(","));
// Output: paint,navigation

Define a measurement contract before installing observers: name, unit, start and end condition, route classification, release identifier, sample rate, and retention period. Ask the browser which entry types it supports. Observe each supported type with the appropriate buffered configuration and disconnect observers on page teardown. For custom operations, use marks around the actual user-visible work and clear marks after measurement. Limit the number of resource entries collected, because image-rich pages can generate many of them. Cross-origin resources may expose limited timing detail unless their owners explicitly allow it. Do not infer that a zero field means instantaneous work; it can mean unavailable data. Sample consistently by a stable random decision for a page view, and keep the sampling fraction in the event so rates can be interpreted. Validate results against a controlled trace before shipping a dashboard.

Cost and boundaries

Observer callbacks add work and retained entries consume memory. Sending every entry from every visit can create a telemetry traffic problem and reveal sensitive routes. A small sample reduces expense but raises uncertainty for uncommon pages. Compare p50 and p95 within comparable cohorts; only compare periods with compatible definitions. Estimate collection cost as sampled page views times entries per view times serialized payload size, then budget both client and ingestion overhead. A missing-observer counter is cheaper than pretending unsupported browsers had perfect results. Treat percentiles computed from tiny cohorts as provisional, and never put personal information in metric names.

Failure trace

Turn off support for one entry type in a test setup and verify collection reports absence instead of a fabricated zero. Start the observer after initial paint and check whether buffered delivery preserves the early entry. Load 62 cross-origin images and confirm the payload cap remains bounded. Move from a case page to the map and prove route attribution follows the intended page-view boundary. Block telemetry transport and ensure form submission still works. Compare a release with 47 samples against one with thousands; the dashboard must show sample counts and avoid a confident claim from the smaller set.

Verification

Unsupported entries are marked missing, never measured as zero.
Each timing event has route, release, unit, and sampling definition.
Telemetry failure does not block the user task.

Practice drill

Instrument a permit search route and an inspection map as separate cohorts. Write an event schema with release, route class, entry type, elapsed milliseconds, supported flag, sample fraction, and collection timestamp. Collect in a browser that has navigation and paint entries, then simulate one without the paint entry. Inspect a late-installed observer, a blocked upload, a cross-origin image, and two route transitions. Produce a table of p50, p95, sample count, and missing count; explain one case where the aggregate improves while the mobile-map cohort becomes slower.

Decision note

A measurement is useful only when its collection boundary and missing-data behavior are explicit.

Common Mistakes

Comparing percentiles from different device mixes without cohorts.
Sending private case paths or complete resource URLs as metric names.
Assuming an observer installed after startup sees all prior entries.

Apply and check

Build Project: permit browser regression investigation and review Web Development: browser performance diagnosis quiz.