Sharing context between network instrumentations and resource timing instrumentation

[joaquin-diaz]

Sharing OTel context between network and resource timing instrumentations

Background

This repo currently has (or will have) two complementary instrumentations:

• Network instrumentation (fetch/XHR): monkey-patches fetch and XMLHttpRequest to create OTel CLIENT spans for each network request.
• Resource timing instrumentation: observes PerformanceResourceTiming entries via PerformanceObserver and emits a browser.resource_timing log for each one, capturing browser-level timing data (DNS, TCP, TLS, queue time, etc.).

The resource timing instrumentation captures entries for all resource types — scripts, stylesheets, images, and also network requests made via fetch/XHR. This means that for every fetch/XHR call there is both a span (from the network instrumentation) and a resource timing log (from the resource timing instrumentation).

Problem

Today, browser.resource_timing logs emitted for fetch/XHR-originated entries carry no trace context. This makes it impossible to correlate them with the corresponding network span in the backend without additional client-side tooling.

Ideally, these logs should carry the traceId and spanId of the fetch/XHR span that triggered them.

Proposed solution

Separation of concerns

The network instrumentation should not observe PerformanceResourceTiming entries on its own — the resource timing instrumentation is already the right place for that. Instead, we can share context between the two using a lightweight coordination layer.

NetworkContextManager

A new shared utility class — NetworkContextManager — acts as the bridge:

• The network instrumentation fires a generic callback (onNetworkSpanEnd) after a span ends, passing the completed span and the request URL. It has no direct dependency on NetworkContextManager.
• The NetworkContextManager is wired to this callback. It stores the span context indexed by URL and timing window (derived from span start/end times), so that concurrent requests to the same URL can be distinguished.
• The resource timing instrumentation exposes a new applyCustomLogRecordData hook (consistent with the pattern already used by navigation and web vitals instrumentations). The hook receives both the mutable log record and the PerformanceResourceTiming entry, allowing the caller to set the log's OTel context before emission.

Wiring

Users (or SDK wrappers) connect the two instrumentations via NetworkContextManager:

const networkCtxManager = new NetworkContextManager();

const fetchInstr = new FetchInstrumentation({
  onNetworkSpanEnd: (span, url) => networkCtxManager.register(span, url),
});

const resourceTimingInstr = new ResourceTimingInstrumentation({
  applyCustomLogRecordData: (logRecord, entry) => {
    logRecord.context = networkCtxManager.getContext(entry);
  },
});

The same NetworkContextManager will work for the XHR instrumentation when it lands, using the same onNetworkSpanEnd hook convention.

Changes required

Network instrumentation (fetch / future XHR)

• Remove the per-request PerformanceObserver and resource timing matching logic — this is no longer the instrumentation's responsibility.
• Add an onNetworkSpanEnd?: (span: Span, url: string) => void config option, called after a span ends.

Resource timing instrumentation

• Add an applyCustomLogRecordData?: (logRecord, entry: PerformanceResourceTiming) => void config option, called before each browser.resource_timing log is emitted.

New: NetworkContextManager

• Exported from the package so SDK wrappers and end users can use it.

Benefits

• Clean separation of concerns: each instrumentation does exactly one job.
• No tight coupling: the network instrumentation doesn't import or know about NetworkContextManager; it just fires a generic callback.
• Extensible: applyCustomLogRecordData is a general-purpose hook that serves other use cases beyond context sharing (e.g. adding custom attributes).
• XHR-ready: the same pattern applies to the XHR instrumentation with no changes to the resource timing side.

[david-luna]

@joaquin-diaz

I'm in favour of the separation of concerns and avoiding the duplication of info. Specially in browser environments where the bandwidth is a precious resource (the less traffic the better).

I have some questions about the solution you propose.

• with this design is it possible that a user could get log correlation with no configuration (default values) for fetch, xhr and resource-timigs instrumentations?
• If not (users should set/get context explicitly). Where this manager should live? Is the user responsible to keep a reference or should the API provide a global register and a getter like the context or trace APIs?

I think log correlation is a feature users might like to have it OOTB. It reduces the friction of data onboarding.
IMHO something like the following code should be possible

const sdk = startBrowserSdk({
  // other options
  instrumentations: [
    // defaults already set context when it could be used by others
    new FetchInstrumentation(),
    new XmlHttpInstrumentation(),
    // instrumentations that are interested in context can get it without extra config
    new ResourceTimingsInstrumentation(),
    // even 3rd party instrumentations can get/set context without forcing the rest to change its configuration
    new MyCustomInstrumentation(),
  ]
});

[david-luna]

@joaquin-diaz

Thanks for sharing your thoughts yesterday in the Browser's SIG. As agreed I'll create a new issue for the configuration sync and defaults. A couple of questions that did come to mind today:

• There are some instrumentations we know for sure they're going to use the manager (fetch, xhr, resource-timings). Could they use the manager internally? I think this would simplify how to handle configuration because it avoids patching user functions to ensure the context is set/get.
• I have my doubts on where to place it. You proposal is to put it in the SDK and this means user instrumentations become dependent of three packages at least (instrumentation, api, sdk). This could imply more surface for breaking changes. Not sure if its a know rule but in the JS SIG we try to make instrumentations depend only on api and instrumentation package. It would be good if we can apply the same here and consider this manager as an instrumentation tool/util rather than a SDK component.

Sorry for asking too much but I'm hesitant of exposing new APIs since the experience in the JS SIG is that once published is very difficult to deprecate/remove. I know all packages here are experimental and breaking changes are expected but still I want to avoid if possible.