All monitors

Each monitor measures one signal of the health of the main thread, of the page or of the device. setupAllMonitors(createBrowserDeps(window, options)) starts each monitor whose dependencies are available in the browser. You can also start one monitor alone, through its factory (createInstrumented...).

The monitors

"All" means that the monitor starts in Chromium, Firefox and Safari. The versions come from browser support. The research gives no versions for the timer APIs, MessageChannel, requestAnimationFrame, IndexedDB and the lifecycle events. The costs come from the code. The timer counts of DriftLag are estimates from the measured timer steps (experiment E3). Each page gives the details.

The overhead benchmark (overhead/overhead.test.ts) measures all monitors together on an idle page, in Chromium in the new headless mode. Its budgets are 3% of one core, 210 timer callbacks and 340 wake-ups each second. The comment of the test gives 22 ms to 25 ms of main-thread time each second for all monitors, on a desktop computer. Measured alone, three loops use most of the budget each second: DriftLag 11 ms, frame timing 14 ms and idle availability 3 ms. Refer to the testing strategy.

Which monitor answers which question

"Lag" is not one quantity. Select the monitor for your question:

The thesis explains why these quantities are different, and the event loop explains the mechanism.

How setupAllMonitors selects the monitors

setupAllMonitors(deps) makes a MonitorRegistry and adds the monitors in this sequence. It adds a monitor only when its dependencies are in deps:

The necessary dependencies are logger, clock, meter, the four timer functions, document and window. All other dependency groups are optional.

The setup also shares these parts between the monitors:

• One absolute clock for the page, made from performance. It reads timeOrigin one time.
• One page ID for the hang journal of the worker and for the peer hang watch (deps.pageId, or a new random ID).
• One set of measurement conditions for the timer-driven monitors.
• An event sink that adds lag.page_view.id to each event, when the page-view vitals operate.
• In a cross-origin-isolated page with a worker: a SharedArrayBuffer, and a DriftLag timer that beats the liveness counter.

Each factory has an error boundary. If the construction of a monitor fails, its handle has no monitor, and the logger gets the warning Failed to create the "<name>" monitor. The other monitors start. A monitor with an observer starts also when the browser does not have its entry type: it logs a warning and gets no entries. For example, Long animation frames start in Firefox, but they get no entries there.

The browser adapter

createBrowserDeps(window, options) gets the dependencies from the browser globals. It examines each optional API, and it binds each browser function to its object. These rules apply:

• SharedArrayBuffer only when crossOriginIsolated is true and the option sharedMemory is not false.
• The hang journal in IndexedDB only with a worker, and only when the option hangJournal is not false.
• crashReport only when window.crashReport has a set() function and the option crashReportContext is not false.
• BroadcastChannel and locks only when the browser has both, and only when the option peerHangWatch is not false. locks.request is bound to navigator.locks.
• memorySource only when the browser has performance.memory or measureUserAgentSpecificMemory().
• pressureSources with the default ["cpu"].

An example

import { init } from "@mark1russell7/otel-ts";
import { createBrowserDeps, createOtelEventSink, createOtelLoggerAdapter, setupAllMonitors } from "@mark1russell7/lag";
import { createLagWorker } from "@mark1russell7/lag/worker";

const otel = init({ serviceName : "shop", endpoint : "http://localhost:4318" });
const worker = createLagWorker();
const monitors = setupAllMonitors(createBrowserDeps(window, {
    logger : createOtelLoggerAdapter(otel.getLogger("lag")),
    meter : otel.getMeter("lag"),
    events : createOtelEventSink(otel.getLogger("lag-events")),
    worker,
}));
// Record the values that wait for a checkpoint, before each flush
otel.onBeforeFlush(() => monitors.flush());

// The monitors that started in this browser
const started = monitors.registry.getAll().filter(handle => handle.monitor !== undefined);
console.log(started.map(handle => handle.name));

AllMonitorHandles gives the registry, stop(), flush() and one accessor for each monitor, for example driftLag or workerMonitor. An accessor gives undefined for a monitor that did not start. stop() stops the monitors in the reverse sequence of their start. flush() records the values that wait for a checkpoint (the page-view vitals). Connect it to the before-flush hook of the exporter: refer to lifecycle.

To keep a monitor off, remove its dependency before the setup:

import { metrics } from "@opentelemetry/api";
import { createBrowserDeps, setupAllMonitors } from "@mark1russell7/lag";

const deps = createBrowserDeps(window, { logger : console, meter : metrics.getMeter("lag") });
// Without its dependencies, the idle monitor does not start
const { requestIdleCallback : _idle, cancelIdleCallback : _cancelIdle, ...withoutIdle } = deps;
const monitors = setupAllMonitors(withoutIdle);
console.log(monitors.idleMonitor === undefined);

Measurement conditions

The timer-driven monitors share one MeasurementConditions. It has two functions:

• pauseWhileHidden(monitor) stops a monitor while the page is hidden or frozen, and starts it again when the page is visible.
• The SampleValidator discards each sample whose window overlaps a hidden, frozen or suspend interval. It holds a sample of 5000 ms or more for 2000 ms, until it knows if the sample was a hang or a suspend.

Two monitors give the evidence of a suspend. The worker gives a heartbeat for which the worker timer was 5 s late or more. The clock-drift monitor gives a forward jump of the wall clock of 1 s or more. Measurement validity explains the rules. The conditions record these metrics:

They also send a lag.stall event for each stall episode, with the attributes kind (hang or suspend) and duration_ms.

Source

• setup-all-monitors.ts: the setup and the sequence of the monitors.
• browser/browser-deps.ts: the browser adapter.
• dep-groups.ts: the dependency groups.
• measurement-conditions.ts and reliability.ts: the measurement conditions.
• metric-catalog.ts: all metrics and events.