@grafana/faro-react-native-tracing 1.3.1 → 2.0.1

package/src/instrumentation.ts

@@ -1,10 +1,11 @@
 import { context, propagation, trace } from '@opentelemetry/api';
-import type { Attributes } from '@opentelemetry/api';
+import type { Attributes, Context, ContextManager } from '@opentelemetry/api';
 import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';
 import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { defaultResource, resourceFromAttributes } from '@opentelemetry/resources';
 import { BatchSpanProcessor, BasicTracerProvider as ReactNativeTracerProvider } from '@opentelemetry/sdk-trace-base';
-import type { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import type { BasicTracerProvider, ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { StackContextManager } from '@opentelemetry/sdk-trace-web';
 import {
   ATTR_SERVICE_NAME,
@@ -13,11 +14,14 @@ import {
 } from '@opentelemetry/semantic-conventions';
 
 import { BaseInstrumentation, getInternalFaroFromGlobalObject, VERSION } from '@grafana/faro-core';
-import type { Transport } from '@grafana/faro-core';
+import type { Faro, OTELApi, Transport } from '@grafana/faro-core';
 
 import { FaroTraceExporter } from './exporters/faroTraceExporter';
 import { getReactNativeDevServerIgnoreUrls } from './instrumentations/devServerIgnoreUrls';
-import { getDefaultOTELInstrumentations } from './instrumentations/getDefaultOTELInstrumentations';
+import {
+  getDefaultOTELInstrumentations,
+  updateDefaultOTELInstrumentations,
+} from './instrumentations/getDefaultOTELInstrumentations';
 import { FaroMetaAttributesSpanProcessor } from './processors/faroMetaAttributesSpanProcessor';
 import { HttpRequestMonitorSpanProcessor } from './processors/httpRequestMonitorSpanProcessor';
 import {
@@ -40,6 +44,53 @@ import { getSamplingDecision } from './utils/sampler';
 // Import React Native TracerProvider
 // Note: We use the base provider since React Native doesn't have a specific one
 
+type FaroWithOtel = Faro & { otel?: unknown };
+const detachedInstrumentations = new WeakSet<Instrumentation>();
+
+/**
+ * Keeps a caller-supplied processor reusable across Faro remove/add cycles.
+ * Explicit TracingInstrumentation.shutdown() remains responsible for the
+ * processor's terminal shutdown.
+ */
+class BorrowedSpanProcessor implements SpanProcessor {
+  constructor(private readonly processor: SpanProcessor) {}
+
+  forceFlush(): Promise<void> {
+    return this.processor.forceFlush();
+  }
+
+  onStart(span: Span, parentContext: Context): void {
+    this.processor.onStart(span, parentContext);
+  }
+
+  onEnding(span: Span): void {
+    this.processor.onEnding?.(span);
+  }
+
+  onEnd(span: ReadableSpan): void {
+    this.processor.onEnd(span);
+  }
+
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+interface TracingRegistration {
+  contextManager?: ContextManager;
+  faro?: FaroWithOtel;
+  faroOtel?: OTELApi;
+  instrumentations: Instrumentation[];
+  ownsContextManager: boolean;
+  ownsContextManagerInstance: boolean;
+  ownsPropagator: boolean;
+  ownsTracerProvider: boolean;
+  previousFaroOtel?: unknown;
+  provider: BasicTracerProvider;
+  shutdownPromise?: Promise<void>;
+  unregisterInstrumentations?: VoidFunction;
+}
+
 /**
  * TracingInstrumentation for React Native
  *
@@ -72,13 +123,18 @@ export class TracingInstrumentation extends BaseInstrumentation {
 
   static SCHEDULED_BATCH_DELAY_MS = 1000;
 
-  private provider?: BasicTracerProvider;
+  private activeRegistration?: TracingRegistration;
+  private defaultInstrumentations?: Instrumentation[];
+  private pendingShutdowns = new Set<Promise<void>>();
+  private suppliedSpanProcessorShutdown?: Promise<void>;
 
   constructor(private options: TracingInstrumentationOptions = {}) {
     super();
   }
 
   initialize(): void {
+    this.destroy();
+
     const options = this.options;
     const attributes: Attributes = {};
 
@@ -151,7 +207,7 @@ export class TracingInstrumentation extends BaseInstrumentation {
     const resource = defaultResource().merge(resourceFromAttributes(attributes));
 
     // Create tracer provider with span processors
-    this.provider = new ReactNativeTracerProvider({
+    const provider = new ReactNativeTracerProvider({
       resource,
       sampler: {
         shouldSample: () => {
@@ -161,7 +217,7 @@ export class TracingInstrumentation extends BaseInstrumentation {
         },
       },
       spanProcessors: [
-        options.spanProcessor ??
+        (options.spanProcessor && new BorrowedSpanProcessor(options.spanProcessor)) ??
           new HttpRequestMonitorSpanProcessor(
             new FaroMetaAttributesSpanProcessor(
               new BatchSpanProcessor(new FaroTraceExporter({ api: this.api }), {
@@ -174,62 +230,102 @@ export class TracingInstrumentation extends BaseInstrumentation {
       ],
     });
 
-    // Register the provider as the global tracer provider
-    // This is CRITICAL for the tracer to generate real trace IDs instead of all zeros
-    trace.setGlobalTracerProvider(this.provider);
-
-    // Register a global ContextManager. Without one, OTel falls back to the NoopContextManager,
-    // which always returns ROOT_CONTEXT — so when `@opentelemetry/instrumentation-fetch` does
-    // `context.with(setSpan(active(), createdSpan), () => _addHeaders(...))` the span set on the
-    // wrapped context is invisible inside `_addHeaders` and `propagation.inject` writes nothing.
-    // `StackContextManager` is pure JS (no DOM/Zone deps) and works in React Native.
-    context.setGlobalContextManager(options.contextManager ?? new StackContextManager().enable());
-
-    // Register the global text-map propagator. Without this, OTel falls back to a
-    // NoopTextMapPropagator and `propagation.inject(...)` becomes a no-op, meaning
-    // `traceparent` / `tracestate` (and `baggage`) headers are never written on the
-    // outbound fetch/XHR — so the backend receives no context and starts a new trace.
-    propagation.setGlobalPropagator(
-      options.propagator ??
-        new CompositePropagator({
-          propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
-        })
-    );
-
-    const {
-      enableFetchInstrumentation,
-      enableXhrInstrumentation,
-      propagateTraceHeaderCorsUrls,
-      fetchInstrumentationOptions,
-      xhrInstrumentationOptions,
-    } = this.options.instrumentationOptions ?? {};
-
-    // Get ignore URLs from transports to prevent infinite loops
-    const ignoreUrls = this.getIgnoreUrls();
-
-    // Register instrumentations
-    registerInstrumentations({
-      instrumentations:
-        options.instrumentations ??
-        getDefaultOTELInstrumentations({
-          ignoreUrls,
-          enableFetchInstrumentation,
-          enableXhrInstrumentation,
-          propagateTraceHeaderCorsUrls,
-          fetchInstrumentationOptions,
-          xhrInstrumentationOptions,
-        }),
-    });
-
-    // Expose OTEL API on the global Faro instance for manual span creation
-    // This allows users to access trace and context APIs via faro.otel
-    const globalFaroInstance = getInternalFaroFromGlobalObject();
-    if (globalFaroInstance) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Extending Faro instance with OTEL API
-      (globalFaroInstance as any).otel = {
-        trace,
-        context,
+    const registration: TracingRegistration = {
+      instrumentations: [],
+      ownsContextManager: false,
+      ownsContextManagerInstance: false,
+      ownsPropagator: false,
+      ownsTracerProvider: false,
+      provider,
+    };
+    this.activeRegistration = registration;
+
+    try {
+      // Register the provider as the global tracer provider
+      // This is CRITICAL for the tracer to generate real trace IDs instead of all zeros
+      if (!trace.setGlobalTracerProvider(provider)) {
+        throw new Error(
+          'Unable to register the Faro OpenTelemetry tracer provider. Remove the existing global tracer provider before initializing Faro tracing.'
+        );
+      }
+      registration.ownsTracerProvider = true;
+
+      // Register a global ContextManager. Without one, OTel falls back to the NoopContextManager,
+      // which always returns ROOT_CONTEXT — so when `@opentelemetry/instrumentation-fetch` does
+      // `context.with(setSpan(active(), createdSpan), () => _addHeaders(...))` the span set on the
+      // wrapped context is invisible inside `_addHeaders` and `propagation.inject` writes nothing.
+      // `StackContextManager` is pure JS (no DOM/Zone deps) and works in React Native.
+      const contextManager = (options.contextManager ?? new StackContextManager()).enable();
+      registration.contextManager = contextManager;
+      registration.ownsContextManagerInstance = options.contextManager == null;
+      registration.ownsContextManager = context.setGlobalContextManager(contextManager);
+
+      // Register the global text-map propagator. Without this, OTel falls back to a
+      // NoopTextMapPropagator and `propagation.inject(...)` becomes a no-op, meaning
+      // `traceparent` / `tracestate` (and `baggage`) headers are never written on the
+      // outbound fetch/XHR — so the backend receives no context and starts a new trace.
+      registration.ownsPropagator = propagation.setGlobalPropagator(
+        options.propagator ??
+          new CompositePropagator({
+            propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
+          })
+      );
+
+      const {
+        enableFetchInstrumentation,
+        enableXhrInstrumentation,
+        propagateTraceHeaderCorsUrls,
+        fetchInstrumentationOptions,
+        xhrInstrumentationOptions,
+      } = this.options.instrumentationOptions ?? {};
+
+      // Get ignore URLs from transports to prevent infinite loops
+      const ignoreUrls = this.getIgnoreUrls();
+
+      const defaultInstrumentationOptions = {
+        ignoreUrls,
+        enableFetchInstrumentation,
+        enableXhrInstrumentation,
+        propagateTraceHeaderCorsUrls,
+        fetchInstrumentationOptions,
+        xhrInstrumentationOptions,
       };
+
+      if (options.instrumentations) {
+        registration.instrumentations = options.instrumentations.flat();
+      } else if (this.defaultInstrumentations) {
+        updateDefaultOTELInstrumentations(this.defaultInstrumentations, defaultInstrumentationOptions);
+        registration.instrumentations = this.defaultInstrumentations;
+      } else {
+        this.defaultInstrumentations = getDefaultOTELInstrumentations(defaultInstrumentationOptions).flat();
+        registration.instrumentations = this.defaultInstrumentations;
+      }
+
+      const instrumentationsNeedingExplicitEnable = registration.instrumentations.filter(
+        (instrumentation) =>
+          detachedInstrumentations.has(instrumentation) && instrumentation.getConfig().enabled === true
+      );
+      registration.unregisterInstrumentations = registerInstrumentations({
+        instrumentations: registration.instrumentations,
+      });
+      registration.instrumentations.forEach((instrumentation) => {
+        detachedInstrumentations.delete(instrumentation);
+      });
+      instrumentationsNeedingExplicitEnable.forEach((instrumentation) => instrumentation.enable());
+
+      // Expose OTEL API on the global Faro instance for manual span creation
+      // This allows users to access trace and context APIs via faro.otel
+      const globalFaroInstance = getInternalFaroFromGlobalObject() as FaroWithOtel | undefined;
+      if (globalFaroInstance) {
+        const faroOtel: OTELApi = { trace, context };
+        registration.faro = globalFaroInstance;
+        registration.faroOtel = faroOtel;
+        registration.previousFaroOtel = globalFaroInstance.otel;
+        globalFaroInstance.otel = faroOtel;
+      }
+    } catch (error) {
+      this.destroy();
+      throw error;
     }
   }
 
@@ -258,12 +354,148 @@ export class TracingInstrumentation extends BaseInstrumentation {
     return [...getReactNativeDevServerIgnoreUrls(), ...transportUrls, ...regexPatterns];
   }
 
-  /**
-   * Shutdown the tracer provider
-   */
+  private detachRegistration(): TracingRegistration | undefined {
+    const registration = this.activeRegistration;
+    if (!registration) {
+      return undefined;
+    }
+    this.activeRegistration = undefined;
+    registration.instrumentations.forEach((instrumentation) => detachedInstrumentations.add(instrumentation));
+
+    let unregistered = false;
+    if (registration.unregisterInstrumentations) {
+      try {
+        registration.unregisterInstrumentations();
+        unregistered = true;
+      } catch (error) {
+        this.logCleanupError('unregister OpenTelemetry instrumentations', error);
+      }
+    }
+    if (!unregistered) {
+      registration.instrumentations.forEach((instrumentation) => {
+        this.runCleanup(`disable ${instrumentation.instrumentationName}`, () => instrumentation.disable());
+      });
+    }
+
+    const { faro, faroOtel } = registration;
+    if (faro && faroOtel && faro.otel === faroOtel) {
+      this.runCleanup('restore faro.otel', () => {
+        if (registration.previousFaroOtel === undefined) {
+          delete faro.otel;
+        } else {
+          faro.otel = registration.previousFaroOtel;
+        }
+      });
+    }
+
+    if (registration.ownsPropagator) {
+      this.runCleanup('clear the OpenTelemetry propagator', () => propagation.disable());
+    }
+    if (registration.ownsContextManager) {
+      this.runCleanup('clear the OpenTelemetry context manager', () => context.disable());
+    } else if (registration.ownsContextManagerInstance && registration.contextManager) {
+      this.runCleanup('disable the unused OpenTelemetry context manager', () => registration.contextManager?.disable());
+    }
+    if (registration.ownsTracerProvider) {
+      this.runCleanup('clear the OpenTelemetry tracer provider', () => trace.disable());
+    }
+
+    return registration;
+  }
+
+  private runCleanup(action: string, cleanup: VoidFunction): void {
+    try {
+      cleanup();
+    } catch (error) {
+      this.logCleanupError(action, error);
+    }
+  }
+
+  private logCleanupError(action: string, error: unknown): void {
+    try {
+      this.logError(`Failed to ${action}:`, error);
+    } catch (_loggingError) {
+      // Cleanup must not fail because a custom logger threw.
+    }
+  }
+
+  private startProviderShutdown(registration: TracingRegistration): Promise<void> {
+    if (!registration.shutdownPromise) {
+      const shutdownPromise = Promise.resolve()
+        .then(() => registration.provider.forceFlush())
+        .catch((error) => {
+          this.logCleanupError('flush the OpenTelemetry tracer provider', error);
+        })
+        .then(() => registration.provider.shutdown());
+      registration.shutdownPromise = shutdownPromise;
+      this.pendingShutdowns.add(shutdownPromise);
+      void shutdownPromise.then(
+        () => this.pendingShutdowns.delete(shutdownPromise),
+        () => this.pendingShutdowns.delete(shutdownPromise)
+      );
+    }
+    return registration.shutdownPromise;
+  }
+
+  private startSuppliedSpanProcessorShutdown(): Promise<void> | undefined {
+    const spanProcessor = this.options.spanProcessor;
+    if (!spanProcessor) {
+      return undefined;
+    }
+    if (!this.suppliedSpanProcessorShutdown) {
+      try {
+        this.suppliedSpanProcessorShutdown = spanProcessor.shutdown();
+      } catch (error) {
+        this.suppliedSpanProcessorShutdown = Promise.reject(error);
+      }
+    }
+    return this.suppliedSpanProcessorShutdown;
+  }
+
+  /** Detach request instrumentations and wait for the tracer provider to flush. */
   async shutdown(): Promise<void> {
-    if (this.provider) {
-      await this.provider.shutdown();
+    const pendingShutdowns = Array.from(this.pendingShutdowns);
+    const registration = this.detachRegistration();
+    if (registration) {
+      pendingShutdowns.push(this.startProviderShutdown(registration));
+    }
+
+    let firstError: unknown;
+    let shutdownFailed = false;
+    for (const shutdownPromise of pendingShutdowns) {
+      try {
+        await shutdownPromise;
+      } catch (error) {
+        if (!shutdownFailed) {
+          firstError = error;
+          shutdownFailed = true;
+        }
+      }
     }
+    const spanProcessorShutdown = this.startSuppliedSpanProcessorShutdown();
+    if (spanProcessorShutdown) {
+      try {
+        await spanProcessorShutdown;
+      } catch (error) {
+        if (!shutdownFailed) {
+          firstError = error;
+          shutdownFailed = true;
+        }
+      }
+    }
+    if (shutdownFailed) {
+      throw firstError;
+    }
+  }
+
+  /** Detach synchronously when Faro removes this instrumentation. */
+  destroy(): void {
+    const registration = this.detachRegistration();
+    if (!registration) {
+      return;
+    }
+    void this.startProviderShutdown(registration).then(undefined, (error) => {
+      this.logCleanupError('shut down the OpenTelemetry tracer provider', error);
+    });
   }
 }

package/src/instrumentations/getDefaultOTELInstrumentations.test.ts

@@ -1,7 +1,7 @@
 import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
 import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
 
-import { getDefaultOTELInstrumentations } from './getDefaultOTELInstrumentations';
+import { getDefaultOTELInstrumentations, updateDefaultOTELInstrumentations } from './getDefaultOTELInstrumentations';
 
 describe('getDefaultOTELInstrumentations', () => {
   it('should return FetchInstrumentation by default', () => {
@@ -9,6 +9,18 @@ describe('getDefaultOTELInstrumentations', () => {
 
     expect(instrumentations).toHaveLength(1);
     expect(instrumentations[0]).toBeInstanceOf(FetchInstrumentation);
+    expect((instrumentations[0] as FetchInstrumentation).getConfig().semconvStabilityOptIn).toBe('http');
+  });
+
+  it.each(['', 'http/dup'])('ignores unsupported fetch convention overrides (%s)', (mode) => {
+    // JavaScript callers can still pass properties absent from the public type.
+    const options = { fetchInstrumentationOptions: { ignoreNetworkEvents: true, semconvStabilityOptIn: mode } };
+    const instrumentations = getDefaultOTELInstrumentations(options).flat();
+    const fetch = instrumentations[0] as FetchInstrumentation;
+    expect(fetch.getConfig().semconvStabilityOptIn).toBe('http');
+
+    updateDefaultOTELInstrumentations(instrumentations, options);
+    expect(fetch.getConfig().semconvStabilityOptIn).toBe('http');
   });
 
   it('should allow enabling XMLHttpRequestInstrumentation', () => {
@@ -49,6 +61,21 @@ describe('getDefaultOTELInstrumentations', () => {
     expect((instrumentations[1] as any)._config.ignoreUrls).toEqual(ignoreUrls);
   });
 
+  it('updates existing Fetch and XMLHttpRequest instrumentation configs', () => {
+    const instrumentations = getDefaultOTELInstrumentations({
+      enableXhrInstrumentation: true,
+      ignoreUrls: [/first-url/],
+    }).flat();
+
+    updateDefaultOTELInstrumentations(instrumentations, {
+      enableXhrInstrumentation: true,
+      ignoreUrls: [/second-url/],
+    });
+
+    expect((instrumentations[0] as FetchInstrumentation).getConfig().ignoreUrls).toEqual([/second-url/]);
+    expect((instrumentations[1] as XMLHttpRequestInstrumentation).getConfig().ignoreUrls).toEqual([/second-url/]);
+  });
+
   it('should set ignoreNetworkEvents to true by default', () => {
     const instrumentations = getDefaultOTELInstrumentations();
 

package/src/instrumentations/getDefaultOTELInstrumentations.ts

@@ -1,12 +1,11 @@
-import type { Span } from '@opentelemetry/api';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
 import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
 
-import { faro, type UserActionInternalInterface, UserActionState } from '@grafana/faro-core';
-
 import type { DefaultInstrumentationsOptions, InstrumentationOption } from '../types';
 
 import {
+  captureFetchUserAction,
   fetchCustomAttributeFunctionWithDefaults,
   xhrCustomAttributeFunctionWithDefaults,
 } from './instrumentationUtils';
@@ -27,31 +26,54 @@ import {
  * @returns Array of OTEL instrumentations
  */
 export function getDefaultOTELInstrumentations(options: DefaultInstrumentationsOptions = {}): InstrumentationOption[] {
-  const {
-    enableFetchInstrumentation = true,
-    enableXhrInstrumentation = false,
-    fetchInstrumentationOptions,
-    xhrInstrumentationOptions,
-    ...sharedOptions
-  } = options;
+  const { enableFetchInstrumentation, enableXhrInstrumentation, fetchConfig, xhrConfig } =
+    resolveDefaultInstrumentationOptions(options);
 
   const instrumentations: InstrumentationOption[] = [];
 
   if (enableFetchInstrumentation) {
-    instrumentations.push(
-      new FetchInstrumentation(createFetchInstrumentationOptions(fetchInstrumentationOptions, sharedOptions))
-    );
+    instrumentations.push(new FetchInstrumentation(fetchConfig));
   }
 
   if (enableXhrInstrumentation) {
-    instrumentations.push(
-      new XMLHttpRequestInstrumentation(createXhrInstrumentationOptions(xhrInstrumentationOptions, sharedOptions))
-    );
+    instrumentations.push(new XMLHttpRequestInstrumentation(xhrConfig));
   }
 
   return instrumentations;
 }
 
+export function updateDefaultOTELInstrumentations(
+  instrumentations: Instrumentation[],
+  options: DefaultInstrumentationsOptions = {}
+): void {
+  const { fetchConfig, xhrConfig } = resolveDefaultInstrumentationOptions(options);
+
+  instrumentations.forEach((instrumentation) => {
+    if (instrumentation instanceof FetchInstrumentation) {
+      instrumentation.setConfig(fetchConfig);
+    } else if (instrumentation instanceof XMLHttpRequestInstrumentation) {
+      instrumentation.setConfig(xhrConfig);
+    }
+  });
+}
+
+function resolveDefaultInstrumentationOptions(options: DefaultInstrumentationsOptions) {
+  const {
+    enableFetchInstrumentation = true,
+    enableXhrInstrumentation = false,
+    fetchInstrumentationOptions,
+    xhrInstrumentationOptions,
+    ...sharedOptions
+  } = options;
+
+  return {
+    enableFetchInstrumentation,
+    enableXhrInstrumentation,
+    fetchConfig: createFetchInstrumentationOptions(fetchInstrumentationOptions, sharedOptions),
+    xhrConfig: createXhrInstrumentationOptions(xhrInstrumentationOptions, sharedOptions),
+  };
+}
+
 function createFetchInstrumentationOptions(
   fetchInstrumentationOptions: DefaultInstrumentationsOptions['fetchInstrumentationOptions'],
   sharedOptions: Record<string, unknown>
@@ -62,26 +84,13 @@ function createFetchInstrumentationOptions(
     ignoreNetworkEvents: true,
     // Keep this here to overwrite the defaults above if provided by the users
     ...fetchInstrumentationOptions,
+    semconvStabilityOptIn: 'http',
     // Always keep this function
     applyCustomAttributesOnSpan: fetchCustomAttributeFunctionWithDefaults(
       fetchInstrumentationOptions?.applyCustomAttributesOnSpan
     ),
-    // Request hook to add user action context
-    requestHook: (span: Span, _: Request | RequestInit) => {
-      try {
-        const currentAction = faro.api.getActiveUserAction();
-        if (
-          currentAction &&
-          (currentAction as unknown as UserActionInternalInterface)?.getState() === UserActionState.Started
-        ) {
-          span.setAttribute('faro.action.user.name', currentAction.name);
-          span.setAttribute('faro.action.user.parentId', currentAction.parentId);
-        }
-      } catch (_error) {
-        // Silently fail - don't log to avoid infinite loops
-        // The span will just not have user action context
-      }
-    },
+    // Also supports callers using a custom processor without the RN request monitor.
+    requestHook: captureFetchUserAction,
   };
 }
 

package/src/instrumentations/instrumentationUtils.ts

@@ -5,6 +5,19 @@ import type { XHRCustomAttributeFunction } from '@opentelemetry/instrumentation-
 
 import { faro, type UserActionInternalInterface, UserActionState } from '@grafana/faro-core';
 
+/** Capture request ownership at start, before the monitor can halt the action. */
+export function captureFetchUserAction(span: Span): void {
+  try {
+    const action = faro.api?.getActiveUserAction?.();
+    if (action && (action as UserActionInternalInterface).getState() === UserActionState.Started) {
+      span.setAttribute('faro.action.user.name', action.name);
+      span.setAttribute('faro.action.user.parentId', action.parentId);
+    }
+  } catch {
+    // Instrumentation must not interrupt the request or log recursively.
+  }
+}
+
 /**
  * FetchError interface matching OpenTelemetry's internal type
  * Note: FetchError is not exported from @opentelemetry/instrumentation-fetch