Context Propagation for Auto-Instrumentation in a Multi-Stage Bootstrap Environment

[gerardalvarez]

Hello OpenTelemetry Community,

I'm working with a large single-page application that has a complex, multi-stage bootstrap process. I'm facing a challenge getting the standard auto-instrumentations (like instrumentation-fetch) to respect a parent span that is created much later in the page lifecycle.

I would greatly appreciate any guidance or recommended patterns for this scenario.

The Goal

I want all automatically generated spans to be children of a single, manually created navigation span. The desired result is a unified trace for the entire page load, like this:

navigation
├── fetch /api/data
├── fetch /api/user
└── my-custom-span

Currently, the navigation span is in one trace, and each fetch call creates its own new, separate trace.

The Architecture & The Problem

Our application's loading process is the source of the issue:

1. telemetry-init.js (First Script): This script loads very early. It is responsible for initializing the WebTracerProvider with ZoneContextManager and calling registerInstrumentations() with getWebAutoInstrumentations(). At this moment, the fetch and XHR instrumentations become active, but they are running in a default, empty context.

2. main-app.js (Later Script): This script loads much later, after many other dependencies have been resolved. It contains our main application logic. It is only at this late stage that we have the necessary information (e.g., from session data) to create the root navigation span that should be the parent of all activity.

Because of this time gap, the auto-instrumentations are "live" long before the parent span they should be attached to even exists.

What I've Tried

• context.with(): Using context.with() around the navigation span creation in our later script doesn't work because the instrumentations have already been registered and don't retroactively adopt the new context.
• Tracer Patching: Attempts to monkey-patch tracer.startSpan() in the later script also seem to fail, likely because the instrumentations have already captured a reference to the original function during their early registration.

The Core Question

What is the recommended approach for making auto-instrumentations aware of a parent span that is only created after they have been registered?

Is there a way to configure getWebAutoInstrumentations so that, at the moment a request is instrumented, it can dynamically "look up" the parent context from a custom, manually managed source?

Illustrative Code

Here is a simplified representation of our setup:

MyManualContext.ts (Our manual context holder)

import { Span } from "@opentelemetry/api";

// A simple singleton stack to hold our manually managed parent span.
export const manualContextStack = {
    _stack: [] as Span[],
    push: (span: Span) => manualContextStack._stack.push(span),
    peek: (): Span | undefined => manualContextStack._stack[manualContextStack._stack.length - 1],
};

telemetry-init-early.ts (The first script to run)

import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import { ZoneContextManager } from "@opentelemetry/context-zone";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { getWebAutoInstrumentations } from "@opentelemetry/auto-instrumentations-web";

// This runs very early in the page lifecycle.
const provider = new WebTracerProvider();
provider.register({ contextManager: new ZoneContextManager() });

registerInstrumentations({
    tracerProvider: provider,
    instrumentations: [getWebAutoInstrumentations()],
});

main-app-init.ts (Runs much later)

import { context, trace } from "@opentelemetry/api";
import { manualContextStack } from "./MyManualContext";

// This function is called late in the bootstrap process.
function initializeApplication() {
    const tracer = trace.getTracer("my-app-tracer");

    // We finally have enough information to create our root span.
    const navigationSpan = tracer.startSpan("navigation");

    // We push it to our manual stack, hoping the auto-instrumentations can find it.
    manualContextStack.push(navigationSpan);

    // Any spans we create manually from here correctly use the parent:
    const ctx = trace.setSpan(context.active(), navigationSpan);
    const childSpan = tracer.startSpan("my-custom-span", undefined, ctx);
    childSpan.end();
}

initializeApplication();

My goal is to find a clean, reliable way for the getWebAutoInstrumentations() registered in the early script to use the navigationSpan from the late script as their parent.

Thank you for your time and any insights you can provide!