document-load: zero-valued navigation timing events are emitted before their own span's start

[ssarma-hub]

Summary

On a navigation entry, addSpanNetworkEvents intentionally includes zero-valued timings. That decision was made deliberately in #5332. What doesn't appear to have been evaluated is where the resulting event lands relative to the span carrying it: @opentelemetry/instrumentation-document-load starts its documentFetch span at fetchStart, not at startTime, so a zero-valued timing is emitted at timeOrigin — before the span begins.

#5332 explicitly flagged this consumer as unknown territory:

It is also unclear if these utilities are intended for anything other than the internal fetch/XHR instrumentation, but they are public API, so if someone uses these functions on the initial page navigation event, then it is possible for the function to see legitimate 0-value inputs.

instrumentation-document-load is that caller. This report is the missing half of that question, not a claim that the compromise was wrong.

Mechanism

1. addSpanNetworkEvents (packages/opentelemetry-sdk-trace-web/src/utils.ts) defaults:

   if (ignoreZeros === undefined) {
     ignoreZeros = resource[PTN.START_TIME] !== 0;
   }

2. For a PerformanceNavigationTiming entry, startTime is unconditionally 0 — Navigation Timing L2 §3.1: "The startTime getter step is to return a DOMHighResTimeStamp with a time value of 0." So ignoreZeros is false for every navigation entry, which is the intended branch.
3. instrumentation-document-load calls addSpanNetworkEvents(fetchSpan, entries, ignoreNetworkEvents) with no explicit ignoreZeros. (entries is a copy built by getPerformanceNavigationEntries; hasKey uses in, so the prototype getter startTime is copied as 0 rather than being absent.)
4. That span is started at PTN.FETCH_START. Since fetchStart > 0 while the zero-valued event resolves to timeOrigin + 0, the event precedes the span start by exactly fetchStart.

Note the reference time for the #4486 ordering check (perfTime >= refTime) was changed from fetchStart to startTime in #5332. For navigation entries that comparison is now always true, so it no longer constrains these events.

Reproduction

Plain-HTTP page load of the OpenTelemetry Demo 2.2.0 (frontend-web), Chromium.

Browser-side input, read directly from the page:

entryType             : "navigation"
protocol              : "http:"
startTime             : 0
fetchStart            : 0.1 ms
secureConnectionStart : 0
timeOrigin            : 1787203601492.6 ms

Collector-side output, taken from the collector's debug exporter at verbosity: detailed — i.e. before any backend ingest, storage or UI:

Name       : documentFetch
Start time : 2026-08-20 05:26:41.492700098 +0000 UTC     (= timeOrigin + fetchStart)

SpanEvent #4
  -> Name      : secureConnectionStart
  -> Timestamp : 2026-08-20 05:26:41.492600098 +0000 UTC (= timeOrigin + 0)

The event is 100µs before its span's start, exactly equal to fetchStart. A second capture with fetchStart = 0.2 ms produced a 200µs offset. Since the magnitude is fetchStart, it is inherently small — on a navigation entry it will always be in this range — and it cannot originate downstream of the SDK.

Observed on 3 of 3 documentFetch spans. Across the same traces, 544 events were checked and every other one falls inside its span; a subresource that genuinely used TLS reported a correctly-ordered secureConnectionStart, so the zero-filtering behaves as intended when startTime is non-zero.

Why report it

Narrowly: a span event carries a timestamp outside the span it belongs to, so the emitted trace is internally inconsistent on its face.

Additionally, 0 in secureConnectionStart is overloaded — no TLS, a cached resource, a resource failing the timing-allow check, and per Fetch's clamp-and-coarsen step a reused connection can produce a non-zero value even on plain HTTP. So a 0 cannot be read as "no secure connection happened", which makes converting it to an absolute instant hard to interpret regardless of ordering.

I am deliberately not claiming downstream breakage. I have not demonstrated a consumer that computes durations from these events, and I am not asking to reverse the cross-origin behaviour restored by #5332 (#3199).

Possible directions

1. instrumentation-document-load passes ignoreZeros: true explicitly for navigation entries.
2. Key the ordering check on the span's own start rather than on the entry's startTime, so an event cannot precede the span regardless of entry type.

Happy to open a PR for either if a preference is indicated.

Environment

• @opentelemetry/sdk-trace-web 2.2.0
• @opentelemetry/auto-instrumentations-web 0.54.0 → @opentelemetry/instrumentation-document-load 0.54.x
• Chromium, plain-HTTP origin
• The defaulting shown above is present on main at time of writing

Filed here because the heuristic and the ordering check live in the core web SDK; the affected caller is instrumentation-document-load in opentelemetry-js-contrib, so please transfer if ownership sits there.

[ssarma-hub]

Follow-up narrowing the scope of this report, so nobody spends time checking it independently.

I tested whether an HTTPS navigation entry can also report secureConnectionStart: 0 — which would have extended this beyond plain-HTTP origins. It does not. Chromium, three cases:

navigation	secureConnectionStart	fetchStart	event before span start?
fresh HTTPS connection	52.3 ms (real handshake)	0.2 ms	no
reused connection	0.1 ms	0.1 ms	no
cache-served (deliveryType: "cache")	0.2 ms	0.2 ms	no

In the reused and cache-served cases the connection timings are collapsed to fetchStart by Fetch's "clamp and coarsen connection timing info" step, rather than being left at 0 — so the event coincides exactly with the span start and stays contained.

So this is scoped to plain-HTTP origins. That is a fair reason to treat it as low priority; I would rather state it than have it found later.

It also means the general shape "a 0 timing becomes an event at timeOrigin" only bites where a field is genuinely left unassigned on a navigation entry, which for secureConnectionStart is the non-TLS case specifically.

[maurya-78]

Hi, I'd like to investigate and work on this issue.

I can reproduce the timestamp ordering problem described for plain-HTTP navigation entries. I’m currently looking into the two possible approaches mentioned in the issue.

Would it be okay if I investigate the ignoreZeros approach first and open a PR if it looks appropriate?

Thanks!

[ssarma-hub]

Thanks for picking this up.

Two things worth flagging first, both about where the work lands rather than whether it's worth doing.

The two directions are in different repos. instrumentation-document-load is in opentelemetry-js-contrib, so direction 1 (ignoreZeros: true for navigation entries) is a PR there. Direction 2 (keying the ordering check on the span's own start) is in this repo, in sdk-trace-web's addSpanNetworkEvents. Worth settling which you're targeting before writing code.

I'm the reporter, not a maintainer — so I can't give you the preference the issue asked for. I'd rather say that than have you read a go-ahead from me as more than it is.

On the substance: direction 1 is the smaller change and it's confined to the caller that's actually affected. The thing to check is that it doesn't quietly undo what #5332 restored — that PR deliberately kept zero-valued timings, and navigation entries are the case it explicitly left open. Scoping ignoreZeros: true to navigation entries specifically, rather than to the instrumentation as a whole, is probably the line that keeps both intact.

One note if you take direction 2: addSpanNetworkEvents receives an api.Span, which doesn't expose a start time, so it would need a narrowing to the SDK Span or an explicit reference-time parameter — an API-shape call a maintainer should make.

Happy to re-run the plain-HTTP repro against a branch if that helps.