JavaScript User Timing Table

Subtraction gives you a number; the timeline gives you an instrument. Six concrete upgrades. Marks and measures appear in the DevTools performance panel (User Timing track) alongside frames, network and layout - your instrumentation sits in context with what the browser was doing, which is where the why of a slow operation lives. They are named, so dashboards and alerts reference stable product-language keys instead of magic constants scattered through the code. They are entries: PerformanceObserver, getEntriesByType and buffered replay come free, which is the entire RUM collection story. They carry detail payloads, so one measure answers duration plus variant plus cohort. They survive refactorings better - timing code drifts out of sync with the code it times, while a named measure pair moves with the function. And they compose with the browser timings on the same axis: your mark sits next to navigationStart-derived paint timings, so catalog-fetched is comparable against first-contentful-paint with no clock juggling. Subtraction is fine for a quick debug; anything that reaches a dashboard deserves the timeline.

Four recurring ones. Wall-clock contamination: mixing Date.now() into the figure - Date steps with NTP and timezone; performance.now() is monotonic, so one clock per figure, ever. Async gaps: measuring start to end across an await chain measures scheduling too - a 'db-query' measure that includes a stalled microtask queue reports storage problems that are actually main-thread congestion; mark immediately around the awaited call, not around the whole handler. First-call inflation: the first measure of any code path pays JIT warmup, cache fills and lazy module init - report the median of many runs, never the first sample, or you are measuring the compiler. And buffer truncation: default buffers cap (150 for marks, 250 for measures in Chrome-family) - long sessions silently drop early entries, which biases every getEntriesByName analysis toward recent activity; either observe-and-ship continuously or raise the buffer and know the cap. There is a fifth micro-lie: coarsened clocks round to fractions of a millisecond by design - durations under ~0.1ms are noise; do not report sub-tick precision as if it were measured.

Ship measures as events with three fields and one discipline. Fields: name (the stable product-language key), duration (the number), detail (the dimensions - variant, endpoint, cohort). The discipline: collect via a single PerformanceObserver with buffered: true, batch and beacon on visibilitychange-to-hidden (the only reliable send moment - sendBeacon or fetch keepalive), and sample if volume demands it (the observer sees every measure; beaconing every one of them from every user is a self-inflicted outage). What to instrument: the operations your product promises - search latency, checkout step durations, offline-sync catch-up - plus one end-to-end measure per critical path, because executives read the end-to-end number and engineers debug the step numbers. What not to instrument: framework internals and render loops (the browser's own long-task and paint timings already cover those), and anything you cannot name in product language - if the dashboard cannot say it in a sentence, the measure will be noise within a sprint. Finally, version the names: measure-name churn silently breaks every historical comparison; treat the taxonomy like an API.

Almost nothing where it matters, with three real edges. Cost: a mark is a nanosecond-scale stamp and a measure a trivial entry append - you can afford them in production at human-scale frequencies; the cost is in the observers and beacons you attach, not the entries. Edge one: buffer growth in SPAs - every navigation adding a dozen marks is a slow leak; clearMeasures/clearMarks on route transitions, or accept the default caps and stream out continuously. Edge two: name collisions - marks share one global namespace per document, so two libraries marking 'start' corrupt each others measures; prefix with your module name. Edge three: cross-realm and worker isolation - performance timelines are per-realm, so a worker marks itself, never your window timeline; postMessage the durations or observe inside the worker and beacon from there. And one trap at the API edge: measure() with nonexistent mark names throws SyntaxError (not a silent null) - which is correct behavior, but in try/catch-heavy startup code it can be swallowed and leave your dashboard mysteriously empty; fail loudly on missing marks in development.