Architecture

The monitors operate on the main thread of the page. They record metrics and events through ports (Meter, EventSink), and an OpenTelemetry setup exports them to the Grafana stack. Select a box on the map to read what it does.

The layers

flowchart TB
    G[Browser globals: window, performance, indexedDB] --> A[Browser adapter: createBrowserDeps]
    A --> D[AllMonitorDeps: dependency groups]
    D --> S[setupAllMonitors: the composition root]
    S --> R[MonitorRegistry]
    R --> H[One MonitorHandle for each monitor]
    H --> M[Monitor class: measures one signal]
    H --> I[Instruments from the metric catalog]
    I --> P[Ports: Meter and EventSink]
    P --> O[OpenTelemetry adapters]

Only the browser adapter reads the browser globals. All other parts get their dependencies as arguments. Thus a test can give a fake clock, fake timers and a fake PerformanceObserver, and examine each rule with exact values.

Inside @mark1russell7/lag

Ports and adapters

The core depends on small interfaces (ports). Adapters connect the ports to real systems.

The worker

The worker bundle (@mark1russell7/lag/worker) operates createWorkerHandler() of the core. The main thread and the worker talk with these messages:

sequenceDiagram
    participant W as Worker
    participant M as Main thread
    participant C as Collector
    W->>M: heartbeat 1
    M->>W: ack 1
    Note over M: A long task starts
    W--xM: heartbeats wait in the queue
    Note over W: 5 s without an ack
    W->>C: hang started (fetch with keepalive)
    W->>W: write the hang journal each second
    Note over M: The long task ends
    M->>W: ack
    W->>M: hang-ended
    W->>C: hang ended

The path of a sample

flowchart LR
    P[Probe: a timer step, a heartbeat, a frame] --> V{Sample validator}
    V -->|overlaps hidden, frozen or suspend| X[Discard: lag_samples_discarded]
    V -->|5000 ms or more| Q[Quarantine for 2000 ms]
    Q -->|overlaps an interval now| X
    X -->|suspend, 5000 ms or more| S[Stall sample, kind suspend]
    Q -->|no evidence| K[Stall sample, kind hang]
    S --> N[Stall episode: lag_stalls]
    K --> N
    V -->|valid| H[Histogram]
    K --> H
    H --> E[Export at the interval and before page hide]

Refer to measurement validity for the rules.

Design rules

The design obeys the SOLID principles:

More rules:

• No globals in the core. Only createBrowserDeps reads window.
• Error boundaries. A factory that fails gives a handle with no monitor, and the other monitors continue. A listener or a report function that throws does not stop the monitor.
• Full teardown. stop() releases each timer, listener, observer and worker loop. The tests make sure that no timer or listener stays. The soak test (soak/soak.test.ts, on request with pnpm test:soak) also operates all monitors for 3 minutes under load. Then it makes sure that no timer, animation frame or idle callback stays, and that the heap did not grow without limit.
• One source for names. Metric names, units and attribute values come only from the catalog.

How to add a monitor

1. Write the monitor class in packages/lag/src. Give it its dependencies in the constructor.
2. Add its metrics and events to metric-catalog.ts.
3. Write its factory in packages/lag/src/instrumented. Make the instruments with createHistogram and createCounter from the catalog.
4. Add one line to setupAllMonitors(), behind the check of its dependencies.
5. Write the unit tests, and add the metrics to the activity of setup-all-monitors.test.ts. The catalog test then makes sure that the metrics agree with the catalog.
6. Write its reference page in packages/site/content/docs/monitors.