DEV Community: Aditya Reddy

The pagehide listener that never ran

Aditya Reddy — Sat, 07 Nov 2026 20:29:54 +0000

TL;DR: I removed a dead pagehide listener from OpenTelemetry's browser batch processors. Moving it to window would have made it run, but it would also have introduced an earlier logs flush that could miss final web-vitals records. The removal shipped in OpenTelemetry JS 3.0.0.

I found it reading the code

The browser BatchSpanProcessor and BatchLogRecordProcessor already flushed when document.visibilityState became hidden. They also registered a pagehide listener as a fallback for an old Safari bug. That listener was attached to document:

    document.addEventListener('pagehide', this._pageHideListener);

That line comes from the removed code in my PR. The browser dispatches pagehide at window, so the document listener never received it during real navigation. The HTML page-transition event definition specifies the window dispatch.

My first version moved the listener to window. I had checked a navigation in Chromium 151, Firefox 153 and WebKit 26.5: the window listener ran in each, and the document listener didn't. Those results are recorded in the PR.

The browser review caught a problem with that change: a working listener would start flushing the logs queue earlier.

The test sent the event to the same wrong place

The old logs test created an event:

    pageHideEvent = new Event('pagehide');

Then it dispatched that event directly on the document:

    describe('by the pagehide event', () => {
      testDocumentHide(() => {
        document.dispatchEvent(pageHideEvent);
      });
    });

These are excerpts from the test before the change. The synthetic event reached the handler because the test chose document as its destination. It exercised the handler without checking where the browser sends pagehide.

Navigate away and keep the callbacks

For the navigation check, the small demo has three observation listeners: pagehide on both objects, plus visibilitychange on document. A link loads a second page in the same tab. Each departing-page callback writes its fields to sessionStorage; the destination displays those saved rows.

Before navigation: one listener on each candidate object, plus the visibility listener. No SDK or exporter is loaded.

The fresh run on November 7, 2026, at 14:14:39 America/Chicago (-06:00), used Chrome 156.0.8078.73 in headless mode. It produced these callbacks:

Order	Listener that ran	`currentTarget`	Visibility	`isTrusted`
1	`window:pagehide`	`window`	`visible`	`true`
2	`document:visibilitychange`	`document`	`hidden`	`true`

The document pagehide listener produced zero callbacks.

Actual destination page from that run. The saved rows came from the departing document; this page doesn't dispatch replacement events.

In the pagehide row, event.target says document, even though the callback ran on the window listener. event.currentTarget says window. The HTML event algorithm uses a legacy target override; the DOM dispatch algorithm sets that target to the document. The target field alone doesn't tell you which listener ran.

The retained event fields include target: document, currentTarget: window and isTrusted: true for pagehide.

This demo observes event dispatch and order. It doesn't run a telemetry exporter or measure record delivery.

Moving to window starts another flush

In the browser review, @overbalance pointed out the hard-navigation sequence: pagehide arrives before visibilitychange. A window listener would start flushing the existing logs before the application's final hidden-state records arrive. The review named final INP, CLS and LCP records as examples.

I had treated the overlap as a narrow case involving a log written by another pagehide handler. In my follow-up, I corrected that: records emitted on visibilitychange could hit it too.

The logs processor's existing _flushAll() explains why. This excerpt is from the source at the PR base:

    if (this._flushing) {
      return;
    }
    this._flushing = true;

A concurrent call returns without waiting for the running flush. That running flush has already taken its set of records:

    let toFlush = this._finishedLogRecords;
    this._finishedLogRecords = [];

New records enter the fresh queue, outside the snapshot the earlier flush took.

Follow one late record

In the review's scenario, the first flush is still running when the application emits its final record. Assume that record arrives before the SDK's hidden-state handler calls flush:

pagehide on window
  proposed listener starts forceFlush()
  earlier records move into the flush snapshot
  export remains in flight

visibilitychange to hidden
  application emits final record into the fresh queue
  SDK calls forceFlush()
  _flushing is still true, so the call returns

page leaves
  final record can remain outside the earlier export

Sequence from the PR review and queue implementation. This is an explanation of the proposed change, not captured exporter output.

The second call doesn't delete the final record. It leaves that record queued while the first export handles its earlier snapshot. If the page leaves before another export opportunity, the record can miss delivery. The guard and snapshot code explain that behavior for logs; this isn't a description of the trace processor's concurrency handling.

The fresh Chrome run above has the event order discussed in the review. Other browsers and transitions need their own captures before treating that order as universal.

The merged change removes the fallback

I removed the pagehide handler, registration and cleanup from both browser processors, along with the synthetic pagehide tests. The merged diff keeps the existing visibilitychange path.

The logs handler at the final PR head still reads:

    this._visibilityChangeListener = () => {
      if (document.visibilityState === 'hidden') {
        void this.forceFlush();
      }
    };
    document.addEventListener(
      'visibilitychange',
      this._visibilityChangeListener
    );

Source at the final PR head. The release also includes separate error handling for that flush, listed as another change in the release notes.

The old Safari fallback no longer needed reviving either. The browser review records that its underlying Safari bug was fixed in 2020, before the project's supported browser baseline.

JS 3.0.0 lists the removal for both processors under Internal. The old document listener never ran on real navigation, so removing it preserved the existing hidden-state flush and avoided introducing the earlier window flush. It didn't redesign the queue or establish a delivery guarantee for every shutdown path.

Check the record after the handler runs

When testing telemetry on navigation, put observation listeners on the actual browser dispatch objects and leave the page through a real navigation. Preserve the callback fields across that transition, including currentTarget, visibility state and isTrusted.

Then test a record emitted late, while an export is still running. Check whether its ID reaches the exporter and whether it belongs to the snapshot the flush took. If the application emits on visibilitychange, check its ordering against the SDK's own handler too.

What broke when I moved Grafana Faro to OpenTelemetry JS 3.0

Aditya Reddy — Wed, 04 Nov 2026 01:51:43 +0000

TL;DR: I opened the three PRs that move Grafana Faro's web SDK onto OpenTelemetry JS SDK 3.0. The version bump was the easy part. What took the time was a deep import the new exports maps reject, and then the tests. Jest was quietly running the Node build, and a disabled XHR instrumentation turned out to still be making spans. All three PRs are open and waiting on review.

Why Faro had to move at all

OpenTelemetry JS SDK 3.0, experimental 0.300 and API 1.10 came out on Oct 20. They only work with each other, so you can't take one and leave the rest. Faro was on 2.x, 0.223 and API 1.9.

That sounds like something you can sit on for a while, and for the stable 2.x packages you can, they're supported until about Oct 2027. The problem showed up somewhere else. The contrib browser instrumentations (document load, user interaction, long task) had already moved to core ^3.0.0. Install one of those next to @grafana/faro-web-tracing and npm resolves @opentelemetry/api to 1.9.1, cause Faro asks for <1.10.0. Instrumentation 0.300 imports logs from the API, and 1.9.1 doesn't have it. So your app breaks on a package you didn't even touch.

The Faro team wrote this up as an epic with the plan. I picked up the steps.

Three PRs, stacked

I could have done it in one PR. It would have been one big diff touching about 30 files, and nobody wants to review that.

PR	What it does	Ships in
#2358	Moves tracing setup to `@opentelemetry/sdk-trace`	any 2.x minor
#2363	Removes deep imports into OTel packages	any 2.x minor
#2364	The actual 3.0 / 0.300 / 1.10 bump	open decision

The first two change nothing for users and work on 2.x, so they can merge whenever. Only the last one raises what your build needs. Stacking them means the risky diff is small and the boring ones can go first.

WebTracerProvider is gone

SDK 3.x drops @opentelemetry/sdk-trace-web and @opentelemetry/sdk-trace-base. Everything Faro used from them is already in @opentelemetry/sdk-trace 2.12, which is why this step can land on 2.x.

The one real change is that WebTracerProvider.register() used to do several things for you. With the plain TracerProvider you do them yourself, in order:

-    provider.register({
-      propagator: new FaroPausablePropagator(/* ... */),
-      contextManager: options.contextManager,
-    });
+    trace.setGlobalTracerProvider(provider);
+    propagation.setGlobalPropagator(new FaroPausablePropagator(/* ... */));
+
+    const contextManager = options.contextManager ?? new StackContextManager();
+    contextManager.enable();
+    context.setGlobalContextManager(contextManager);

The order matters more than it looks. The context manager has to be enabled before it's registered, and a second Faro instance must not register again over the first. I wrote tests for each of those paths, cause that's exactly the kind of thing that works on the happy path and breaks for the one app that passes its own propagator.

Side effect I didn't plan for: the tracing IIFE went from 90,474 to 87,299 bytes minified. Dropping a package you don't use is a nice way to lose 3 KB.

The exports map says no

This is the one that would have broken the upgrade if you just bumped versions.

All the 0.300 packages declare an exports map in package.json. Faro had imports straight into build/src of @opentelemetry/otlp-transformer, for the OTLP payload types and for createExportTraceServiceRequest and JSON_ENCODER. With an exports map, any subpath that isn't listed fails to resolve. It doesn't matter if the file is sitting right there.

Pointing the paths at the new dist/ layout doesn't help either. Unlisted is unlisted.

So I moved the OTLP types (IResourceSpans, IKeyValue, ESpanKind and the rest) into @grafana/faro-core, and swapped the exporter over to the public JsonTraceSerializer:

- import { JSON_ENCODER } from '@opentelemetry/otlp-transformer/build/src/common/utils';
- import { createExportTraceServiceRequest } from '@opentelemetry/otlp-transformer/build/src/trace/internal';
+ import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer';

- const traceEvent = createExportTraceServiceRequest(spans, JSON_ENCODER);
+ const traceEvent: TraceEvent = JSON.parse(
+   new TextDecoder().decode(JsonTraceSerializer.serializeRequest(spans))
+ );

That's one extra encode and parse per batch. I don't love it, though it's the public API in both 0.223 and 0.300 and the payload that goes out is the same. A snapshot test of the trace payload and the derived faro.tracing.* event now pins that down.

One detail I'd point out to anyone doing the same thing. I didn't copy ESpanKind as a TypeScript enum. TraceEvent is public through faro.api.pushTraces, and enums from two different declarations aren't assignable to each other. If Faro shipped its own enum, any app building payloads with otlp-transformer's enum would stop compiling. A const object with a numeric union type keeps both working.

This step also took @opentelemetry/otlp-transformer out of core and the OTLP transport, they only used its types. Without that, every Faro user would pick up 0.300's engines.node >=22.15.0, not just the ones using tracing.

The bump, and what it found

The version change itself is a few lines in package.json. core, resources and sdk-trace to ^3.0.0, the experimental packages to ^0.300.0, the API to ^1.10.0. Typecheck passed without a single change. That was honestly a bit suspicious.

Jest was running the Node build

Then Jest. Under Jest 30 with jsdom, OTel's packages resolve to their Node builds, not the browser ones. Nothing fails. You just test the wrong code. This is a one-line test that prints SDK_INFO from @opentelemetry/core 3.0, run once without the resolver and once with it:

SDK_INFO reporting nodejs inside a browser test environment is the tell. The 3.x migration guide has a Jest resolver for this, and adding it flips it to webjs. If you have your own Jest setup with OTel 3.x and jsdom, check this before you trust your green tests.

A disabled instrumentation that kept tracing

Running the tests against the real XMLHttpRequestInstrumentation (the old ones mocked it) turned up a bug that wasn't about 3.0 at all. FaroXhrInstrumentation overrides _patchOpen, and the override didn't check _enabled like the parent does. disable() leaves open patched, so a disabled Faro XHR instrumentation kept creating spans.

It's a one-line check. It's also the kind of bug that lives for years cause the unit tests mock the exact thing that would catch it.

Size and tests

The tracing bundle grows from 74.8 kB to 76.7 kB (22.1 to 22.5 kB gzipped) against #2363. The web-sdk and core bundles stay the same size, and there's no Node platform code in the browser bundle.

On the #2364 head the full suite passes, 1,218 unit tests across seven packages with one skipped.

What I checked outside the repo

Unit tests only tell you so much for a change like this, so I packed the packages and tried them in real apps:

A webpack 5.54 app and a Vite 7 app both build and run. Fetch and XHR spans get exported with telemetry.sdk.language set to webjs, and the faro.tracing.* events still go out.
The .d.ts files typecheck with both bundler and node16 module resolution.
On the other end, Alloy's faro.receiver uses the collector's ptrace.JSONUnmarshaler, so span attributes with object, array and bytes values still parse.

I also ran my own otel-js-upgrade codemod as a dry run on the #2363 tree. It proposed the same version bumps and no code changes. Which is the right answer, and kind of the point of this post: the parts that took time are the ones no codemod can see.

What's still open

The 3.0 PR has no ! in the title on purpose. Whether this ships as Faro v3 or a 2.x minor is still an open call in the epic. Faro's own API doesn't change, but the floor for your build does: webpack 5.54+, Jest 29.4+ or Parcel with packageExports, and Node 22.15+ for installs. Those are old versions to still be on, though a minor release breaking someone's build is still a minor release breaking someone's build.

There's one thing I left alone. sendFaroEvents turns attribute values into strings with String(), so array and object values come out as [object Object] in the derived events. Arrays already did that on 2.x, 3.x just lets objects through too. That's a small follow up if the maintainers want JSON there.

After this, the next step is #2340, replacing Faro's fetch and XHR instrumentations with the ones from the OpenTelemetry Browser SIG. That changes trace data, so it's a bigger conversation.

If you're on Faro today

Until the upgrade ships, if you add contrib browser instrumentations next to Faro, pin the last versions on 2.x:

npm i @opentelemetry/instrumentation-document-load@0.68.0 \
  @opentelemetry/instrumentation-user-interaction@0.67.0 \
  @opentelemetry/instrumentation-long-task@0.67.0

That keeps @opentelemetry/api on one version and your app out of the logs import error.

Why your INP can fall after one more click

Aditya Reddy — Mon, 02 Nov 2026 21:49:13 +0000

By Aditya Reddy

Say you have a page with 49 interactions. The slowest took 480 ms, followed by 320 ms and 240 ms. Everything else was faster. Your INP is 480 ms.

Now click something fast. You have changed no code, and that slow interaction still takes 480 ms. The score for the visit drops to 320 ms anyway.

That's the part of INP I wanted to explain in my Event Timing specification PR. The PR is still open. A single number on a dashboard hides quite a bit of bookkeeping.

What happened at click 50?

INP skips one longest interaction for every complete group of 50 interactions. At 49, it picks the longest. At 50, it picks the second longest. The INP guide explains the reason for excluding these outliers on pages with lots of interactions.

For our example, assuming all the extra interactions are below 240 ms:

Interactions so far	Longest values skipped	INP candidate
49	0	480 ms
50	1	320 ms
99	1	320 ms
100	2	240 ms

So you can cross two of these boundaries and go from 480 to 240 ms without fixing the 480 ms interaction. Nice dashboard, same slow click.

The selection code in web-vitals amounts to this, with the latencies sorted from longest to shortest:

const skip = Math.floor(interactionCount / 50);
const index = Math.min(skip, descendingLatencies.length - 1);
const candidate = descendingLatencies[index];

You need at least one candidate for this fragment. It is only the selection step, not a complete collector. web-vitals retains up to ten of the longest interactions, so the list can be much shorter than the interaction count.

Count interactions, not event entries

There is another place to get the numbers wrong before you even reach that selection.

A click can leave several PerformanceEventTiming entries. Take these made-up values from one visit:

Interaction ID	Event	Duration
7	pointerdown	320 ms
7	pointerup	296 ms
7	click	280 ms
14	click	480 ms
21	keydown	240 ms

The first three rows belong to one interaction. Its latency is 320 ms, the longest duration in that group. Adding them gives 896 ms, but those durations overlap.

Five rows here give us three interactions, with latencies of 320, 480 and 240 ms. Group by the nonzero interactionId. Leave entries with ID zero out of this calculation. The Event Timing spec describes how those IDs group related events.

Your observer may have missed some of it

For entries of type event, the default duration threshold is 104 ms. You can register an observer with durationThreshold: 16 to receive shorter events going forward. That does not bring back all the fast events from before registration.

Even with buffered delivery, you only get the earlier entries that were kept under the default threshold. This is covered in the spec's measurement section.

That's why the total interaction count and your observed list length need to stay separate. A fast interaction can increase the count without appearing in that list. Lowering the threshold late won't recover its duration.

I would use web-vitals for production collection. There is first-input handling, page visibility and back/forward cache restoration to account for too. Code running in one window also cannot see every interaction in an embedded frame.

When debugging the score, keep the selected interaction's ID and latency along with the total count. If the score drops, check which interaction it picked. And if you are fixing that 480 ms click, compare the click itself before and after the change under similar conditions.

The proposed spec section puts the grouping, selection, observer threshold and retained-list limit together. The fast click at interaction 50 is a useful example of why those details matter.

How one Desk Studio job gets from roughs to sign-off

Aditya Reddy — Tue, 20 Oct 2026 04:43:48 +0000

The awkward part of a design job is deciding whether it's done. A file exists, the headline fits, and it's easy to accept it cause opening another round means deciding what to ask for. I built Desk Studio around that decision. I wanted the roughs and the reason for the pick to stay visible, and I wanted a failed check to send the file back with something specific to fix.

Here's how that worked on the studio's own launch card. The saved job state has the pick, each round's proof result and scores, and the cost by tier. The golden record keeps the final result. It finished at 8.9 over three polish rounds, costing $1.34 at list price. Those are this job's results, not a promise about the next one.

The whole job as a cartoon: three roughs on Sonnet, the pick on Opus, polish on Haiku, proof with no model, the sign-off on Opus, then every signed-off piece back to you.

Give the pick something to choose from

The launch card started with three directions: editorial split, type only, and frame. These were separate roughs made by the UI Designer at the senior tier. The point of a rough is to expose a layout decision while changing direction is still cheap. If everything already looks finished, it's tempting to spend the next round adjusting details in a direction that never deserved the pick.

The Art Director chose rough 2, the type-only direction. The saved reason is useful: the headline read first at both sizes, the small lamp was the only amber element, and the fixes were type sizes rather than layout. That gives the builder a boundary. Keep the structure that earned the pick and work on the type.

The card had LinkedIn and Instagram post sizes. A direction had to work across both, so the pick was made from renders. Reading the source wouldn't show whether the headline actually won attention at each size.

Put the revisions where they're cheap

After the pick, the UI Designer moved to the builder tier for polish. The launch job used Sonnet for roughs, Haiku for the revisions, and Opus for the pick and sign-offs. Those assignments are in the state alongside the completed desk runs.

I want the expensive judgment to arrive with a concrete job to do. The builder already has a chosen direction, the notes and a screenshot. It can spend its round revising that file, then hand back something the next check can inspect. Starting from an empty prompt again would lose the decision that was just made.

This also makes the cost breakdown interesting. The job's director work cost $0.81, rounded, for the pick and sign-offs. Senior work was $0.43 and builder work $0.10. The underlying total is $1.3354, which rounds to $1.34. These are recorded list-price costs, not a subscription bill or a measured saving against hiring someone. Most of this particular job's cost went into choosing and reviewing.

Proof gets the rendered file

Each polished file goes through proof before the Creative Director scores it. Proof checks the rendered pixels for text contrast, along with checks for overflow, clipping, safe zones, palette, type scale and required copy. There's no model deciding whether to waive a mechanical failure. A failure goes back to the builder with the screenshot.

The launch card passed proof in every round. To see an actual rejection, look at the separate dashboard demo card's state. Its first polish failed a safe-zone check: “deskstudio.ai” sat 32px from the top edge on LinkedIn, while the safe zone started at 38px. The state keeps that note and the failed proof result. The following round passed proof and proceeded to sign-off.

That's a small error, though it's exactly the sort of thing I want a check to catch before asking for a judgment on composition. The text being present isn't enough. Where it lands in the rendered output matters. Keeping the failed result also means the final screenshot doesn't erase the work needed to reach it.

An average can still fail

The Creative Director scores hierarchy, typography, spacing, colour, composition, originality, brand fit and copy. The visual rubric requires every axis to reach 8 and the average to reach 8.5. These are the studio's own evaluations. They aren't independent ratings of design quality.

The launch card shows why both conditions matter. Its first round averaged 8.4, with originality at 7. The next round reached an average of 8.5, but originality was still 7, so it failed again. An average alone would have accepted that second round.

The third round passed at 8.9. Originality reached 8 and the other axes were 9. That is a more useful record than a final score on its own, cause it shows which weakness kept the job open. It also keeps proof separate from taste: every launch-card round passed the mechanical checks, and the first two still failed the design review.

Try a job you can inspect

In Claude Code, install the plugin:

/plugin install desk --marketplace adityareddy-dev/deskstudio

In Cursor, Codex, Gemini CLI, Copilot, Windsurf or OpenCode, add it to the project:

npx deskstudio add

Then ask your coding agent for a design in plain words. The installer adds the desk briefs and an instruction block so the agent can run the job. The gallery links the outputs, and the public repository retains the records used here.

The API-key paths remain unverified end to end. I wouldn't infer that they work just cause the adapters exist. For a first job, use an output you can judge yourself, read the pick reason, and check the weakest axis against the rendered file before accepting the sign-off.

Why the OpenTelemetry browser SDK wouldn't start on Safari 17

Aditya Reddy — Fri, 02 Oct 2026 22:23:11 +0000

On September 30 someone filed an issue on the OpenTelemetry browser SDK. startBrowserSdk was throwing TypeError: URL.parse is not a function on older browsers, so the SDK never started there at all.

Nothing caught the error, so an app that started the SDK on load (the issue's example was while rendering a React provider) went down with it. Blank page, in production builds. The issue came with a clean reproduction too (Chromium 125 failed, Chromium 127 started fine), which made it easy to pick up.

I went looking and it was one line. The SDK checks the export URL every time it starts, and it did that with URL.parse:

const parsed = URL.parse(url);

Problem is, URL.parse is new. Safari only got it in version 18, Chrome and Firefox in 126, all in 2024. Anyone on Safari 17, which includes iPhones still on iOS 17, or on a Chrome or Firefox older than 126 doesn't have it. The older way, new URL(url), has worked everywhere for years. It throws on a bad URL instead of returning null though, which is a big part of why URL.parse was added in the first place.

So the fix goes back to the try/catch:

let parsed: URL | null;
try {
  // Not `URL.parse`, which Safari < 18 and Chrome/Firefox < 126 lack.
  parsed = new URL(url);
} catch {
  parsed = null;
}

A URL that doesn't parse, or isn't http or https, still returns null and logs an error like before, and the SDK still refuses to start on it. Other parts of the repo already parsed URLs this way, so it wasn't a new pattern for anyone reviewing it.

Testing was the annoying part, cause I didn't have an old Safari lying around. What I did instead was delete URL.parse in current Chrome and start the SDK:

const urlParse = Object.getOwnPropertyDescriptor(URL, 'parse');
Reflect.deleteProperty(URL, 'parse');

try {
  browserSdk = startBrowserSdk({ /* short batch delay for the test */ });
  // emit a log and a span, then wait for the export
} finally {
  if (urlParse) {
    Object.defineProperty(URL, 'parse', urlParse);
  }
}

That test failed on main with the exact error from the issue and passed with the fix. I never ran it on a real Safari 17 or Chrome 125, and I said so in the PR.

The bit I keep thinking about is why lint didn't catch it. The repo runs eslint-plugin-baseline-js set to available: 'widely', which is there to stop exactly this kind of thing. It let URL.parse through cause its data counts URL.parse as part of the older url feature, and that one has been widely available for a long time. So a method Safari has had for about two years passed the check. I left the lint config alone, it felt like its own conversation.

David Luna merged it on October 2.

PR: https://github.com/open-telemetry/opentelemetry-browser/pull/447
Issue: https://github.com/open-telemetry/opentelemetry-browser/issues/445