@grafana/faro-react-native-tracing 1.3.0 → 2.0.0

package/README.md

@@ -41,6 +41,23 @@ const faro = initializeFaro({
 
 That's it! HTTP requests via `fetch()` are now automatically traced (and correlated with user actions when user action tracking is enabled) and sent to your Faro collector.
 
+## HTTP span and event conventions
+
+Built-in fetch tracing uses OpenTelemetry's [stable HTTP conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#name),
+with span names such as `GET` and `POST`. Attributes include `http.request.method`,
+`url.full`, `server.address`, `server.port`, and `http.response.status_code`.
+Successful responses leave status UNSET; ordinary 4xx/5xx responses set ERROR
+and a string `error.type`. There is no fetch convention mode setting.
+
+The `faro.tracing.fetch` event keeps `http.method`, `http.url`, `http.status_code`,
+`http.host`, and `http.scheme`. Event attributes, including `duration_ns`, are
+strings. Events retain session and trace/span context and use the shared event
+pipeline for deduplication and transport hooks. Optional XHR tracing and custom
+instrumentations use their own conventions.
+
+Fetch spans capture the active user action at request start. A delayed fetch
+event can still be associated with a later action through event buffering.
+
 ## Fetch vs XHR in React Native
 
 By default, this package traces `fetch()` requests only.
@@ -209,6 +226,10 @@ new TracingInstrumentation({
 });
 ```
 
+A custom span processor remains reusable when Faro removes and later re-adds the tracing instrumentation. Removal
+flushes the processor without shutting it down. Calling `TracingInstrumentation.shutdown()` shuts it down and is
+terminal for that processor; use a new processor before initializing the instrumentation again.
+
 ## Usage Examples
 
 ### Automatic HTTP Tracing
@@ -665,6 +686,10 @@ const { trace } = faro.otel; // Error!
 
 **Solution:** This should be automatic. If you're using a custom span processor or custom instrumentations, ensure you're not overriding the tracer provider registration.
 
+If another global OpenTelemetry tracer provider is already registered, tracing initialization fails with a clear
+error instead of installing request instrumentation that cannot export through Faro. Remove the duplicate provider
+registration before initializing `TracingInstrumentation`.
+
 ### Spans missing user/session/device context
 
 **Cause:** FaroMetaAttributesSpanProcessor is not wrapping your span processor.
@@ -727,9 +752,17 @@ class TracingInstrumentation extends BaseInstrumentation {
   constructor(options?: TracingInstrumentationOptions);
   initialize(): void;
   shutdown(): Promise<void>;
+  destroy(): void;
 }
 ```
 
+`shutdown()` detaches HTTP instrumentation before waiting for the tracer provider to flush. Faro calls `destroy()`
+when the instrumentation is removed; it detaches immediately and completes provider shutdown in the background.
+Both methods are safe to call more than once.
+
+When tracing is removed and later re-added, reuse the same `TracingInstrumentation` instance so the default fetch
+and XHR patches are reused as well.
+
 **Options:**
 
 ```typescript

package/dist/cjs/exporters/faroTraceExporter.js

@@ -38,6 +38,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FaroTraceExporter = void 0;
 var core_1 = require("@opentelemetry/core");
+var utils_1 = require("@opentelemetry/otlp-transformer/build/src/common/utils");
 var internal_1 = require("@opentelemetry/otlp-transformer/build/src/trace/internal");
 var faro_core_1 = require("@grafana/faro-core");
 var internalLogger = (0, faro_core_1.createInternalLogger)();
@@ -65,7 +66,7 @@ var FaroTraceExporter = /** @class */ (function () {
         }
         try {
             // Convert spans to OTLP format
-            var traceEvent = (0, internal_1.createExportTraceServiceRequest)(spans, { useHex: true, useLongBits: false });
+            var traceEvent = (0, internal_1.createExportTraceServiceRequest)(spans, utils_1.JSON_ENCODER);
             // Send traces to Faro
             this.config.api.pushTraces(traceEvent);
             // Send Faro events for CLIENT spans (HTTP requests, etc.)

package/dist/cjs/exporters/faroTraceExporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"faroTraceExporter.js","sourceRoot":"","sources":["../../../src/exporters/faroTraceExporter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAAuD;AAEvD,qFAA2G;AAG3G,gDAA0D;AAE1D,IAAM,cAAc,GAAG,IAAA,gCAAoB,GAAE,CAAC;AAI9C,qEAA2D;AAE3D;;;;;;;;;GASG;AACH;IAGE,2BAAoB,MAA+B;QAA/B,WAAM,GAAN,MAAM,CAAyB;QAF3C,gBAAW,GAAG,KAAK,CAAC;IAE0B,CAAC;IAEvD,kCAAM,GAAN,UAAO,KAAqB,EAAE,cAA8C;QAC1E,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,cAAc,CAAC,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACtF,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,+BAA+B;YAC/B,IAAM,UAAU,GAAG,IAAA,0CAA+B,EAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;YAEhG,sBAAsB;YACtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;YAEvC,0DAA0D;YAC1D,uDAAuD;YACvD,IAAA,wCAAc,EAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAEzC,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2BAA2B;YAC3B,cAAc,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;YACzE,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAEK,oCAAQ,GAAd;;;gBACE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBACxB,sBAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAC;;;KACnC;IAEK,sCAAU,GAAhB;;;gBACE,4DAA4D;gBAC5D,sBAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAC;;;KACnC;IACH,wBAAC;AAAD,CAAC,AAxCD,IAwCC;AAxCY,8CAAiB","sourcesContent":["import { ExportResultCode } from '@opentelemetry/core';\nimport type { ExportResult } from '@opentelemetry/core';\nimport { createExportTraceServiceRequest } from '@opentelemetry/otlp-transformer/build/src/trace/internal';\nimport type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';\n\nimport { createInternalLogger } from '@grafana/faro-core';\n\nconst internalLogger = createInternalLogger();\n\nimport type { FaroTraceExporterConfig } from '../types';\n\nimport { sendFaroEvents } from './faroTraceExporter.utils';\n\n/**\n * FaroTraceExporter for React Native\n *\n * Exports OpenTelemetry spans to Faro backend using pushTraces API.\n *\n * IMPORTANT: To avoid infinite loops:\n * - Uses internalLogger instead of console\n * - Does NOT log during export (except errors)\n * - Relies on Faro's internal deduplication\n */\nexport class FaroTraceExporter implements SpanExporter {\n  private _isShutdown = false;\n\n  constructor(private config: FaroTraceExporterConfig) {}\n\n  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {\n    if (this._isShutdown) {\n      internalLogger.error('FaroTraceExporter: Cannot export spans, exporter is shut down');\n      resultCallback({ code: ExportResultCode.FAILED });\n      return;\n    }\n\n    try {\n      // Convert spans to OTLP format\n      const traceEvent = createExportTraceServiceRequest(spans, { useHex: true, useLongBits: false });\n\n      // Send traces to Faro\n      this.config.api.pushTraces(traceEvent);\n\n      // Send Faro events for CLIENT spans (HTTP requests, etc.)\n      // This is done WITHOUT logging to avoid infinite loops\n      sendFaroEvents(traceEvent.resourceSpans);\n\n      resultCallback({ code: ExportResultCode.SUCCESS });\n    } catch (error) {\n      // Only log critical errors\n      internalLogger.error('FaroTraceExporter: Failed to export spans', error);\n      resultCallback({ code: ExportResultCode.FAILED });\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    this._isShutdown = true;\n    return Promise.resolve(undefined);\n  }\n\n  async forceFlush(): Promise<void> {\n    // No-op for now - spans are sent immediately via pushTraces\n    return Promise.resolve(undefined);\n  }\n}\n"]}
+{"version":3,"file":"faroTraceExporter.js","sourceRoot":"","sources":["../../../src/exporters/faroTraceExporter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAAuD;AAEvD,gFAAsF;AACtF,qFAA2G;AAG3G,gDAA0D;AAE1D,IAAM,cAAc,GAAG,IAAA,gCAAoB,GAAE,CAAC;AAI9C,qEAA2D;AAE3D;;;;;;;;;GASG;AACH;IAGE,2BAAoB,MAA+B;QAA/B,WAAM,GAAN,MAAM,CAAyB;QAF3C,gBAAW,GAAG,KAAK,CAAC;IAE0B,CAAC;IAEvD,kCAAM,GAAN,UAAO,KAAqB,EAAE,cAA8C;QAC1E,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,cAAc,CAAC,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACtF,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,+BAA+B;YAC/B,IAAM,UAAU,GAAG,IAAA,0CAA+B,EAAC,KAAK,EAAE,oBAAY,CAAC,CAAC;YAExE,sBAAsB;YACtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;YAEvC,0DAA0D;YAC1D,uDAAuD;YACvD,IAAA,wCAAc,EAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAEzC,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2BAA2B;YAC3B,cAAc,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;YACzE,cAAc,CAAC,EAAE,IAAI,EAAE,uBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAEK,oCAAQ,GAAd;;;gBACE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBACxB,sBAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAC;;;KACnC;IAEK,sCAAU,GAAhB;;;gBACE,4DAA4D;gBAC5D,sBAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAC;;;KACnC;IACH,wBAAC;AAAD,CAAC,AAxCD,IAwCC;AAxCY,8CAAiB","sourcesContent":["import { ExportResultCode } from '@opentelemetry/core';\nimport type { ExportResult } from '@opentelemetry/core';\nimport { JSON_ENCODER } from '@opentelemetry/otlp-transformer/build/src/common/utils';\nimport { createExportTraceServiceRequest } from '@opentelemetry/otlp-transformer/build/src/trace/internal';\nimport type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';\n\nimport { createInternalLogger } from '@grafana/faro-core';\n\nconst internalLogger = createInternalLogger();\n\nimport type { FaroTraceExporterConfig } from '../types';\n\nimport { sendFaroEvents } from './faroTraceExporter.utils';\n\n/**\n * FaroTraceExporter for React Native\n *\n * Exports OpenTelemetry spans to Faro backend using pushTraces API.\n *\n * IMPORTANT: To avoid infinite loops:\n * - Uses internalLogger instead of console\n * - Does NOT log during export (except errors)\n * - Relies on Faro's internal deduplication\n */\nexport class FaroTraceExporter implements SpanExporter {\n  private _isShutdown = false;\n\n  constructor(private config: FaroTraceExporterConfig) {}\n\n  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {\n    if (this._isShutdown) {\n      internalLogger.error('FaroTraceExporter: Cannot export spans, exporter is shut down');\n      resultCallback({ code: ExportResultCode.FAILED });\n      return;\n    }\n\n    try {\n      // Convert spans to OTLP format\n      const traceEvent = createExportTraceServiceRequest(spans, JSON_ENCODER);\n\n      // Send traces to Faro\n      this.config.api.pushTraces(traceEvent);\n\n      // Send Faro events for CLIENT spans (HTTP requests, etc.)\n      // This is done WITHOUT logging to avoid infinite loops\n      sendFaroEvents(traceEvent.resourceSpans);\n\n      resultCallback({ code: ExportResultCode.SUCCESS });\n    } catch (error) {\n      // Only log critical errors\n      internalLogger.error('FaroTraceExporter: Failed to export spans', error);\n      resultCallback({ code: ExportResultCode.FAILED });\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    this._isShutdown = true;\n    return Promise.resolve(undefined);\n  }\n\n  async forceFlush(): Promise<void> {\n    // No-op for now - spans are sent immediately via pushTraces\n    return Promise.resolve(undefined);\n  }\n}\n"]}

package/dist/cjs/exporters/faroTraceExporter.utils.js

@@ -5,6 +5,36 @@ var internal_types_1 = require("@opentelemetry/otlp-transformer/build/src/trace/
 var faro_core_1 = require("@grafana/faro-core");
 var internalLogger = (0, faro_core_1.createInternalLogger)();
 var DURATION_NS_KEY = 'duration_ns';
+/** Map stable OTel span attributes to Faro's fetch event contract. */
+function projectFetchEventAttributes(attributes) {
+    var _a, _b, _c;
+    var fields = {
+        'http.request.method': 'http.method',
+        'url.full': 'http.url',
+        'http.response.status_code': 'http.status_code',
+    };
+    for (var _i = 0, _d = Object.entries(fields); _i < _d.length; _i++) {
+        var _e = _d[_i], spanField = _e[0], eventField = _e[1];
+        if (attributes[spanField] != null) {
+            attributes[eventField] = attributes[spanField];
+            delete attributes[spanField];
+        }
+    }
+    var url = attributes['http.url'];
+    if (url) {
+        try {
+            var parsed = new URL(url);
+            attributes['http.host'] = (_a = attributes['http.host']) !== null && _a !== void 0 ? _a : parsed.host;
+            attributes['http.scheme'] = (_b = attributes['http.scheme']) !== null && _b !== void 0 ? _b : parsed.protocol.replace(':', '');
+        }
+        catch (_f) {
+            // Keep the captured URL even if it cannot supply host/scheme metadata.
+        }
+    }
+    delete attributes['server.address'];
+    delete attributes['server.port'];
+    attributes['component'] = (_c = attributes['component']) !== null && _c !== void 0 ? _c : 'fetch';
+}
 /**
  * Send Faro events for CLIENT spans (HTTP requests, navigation, etc.)
  *
@@ -45,6 +75,9 @@ function sendFaroEvents(resourceSpans) {
                         var attribute = _g[_f];
                         faroEventAttributes[attribute.key] = String(Object.values(attribute.value)[0]);
                     }
+                    if ((scope === null || scope === void 0 ? void 0 : scope.name) === '@opentelemetry/instrumentation-fetch') {
+                        projectFetchEventAttributes(faroEventAttributes);
+                    }
                     // Add span duration in nanoseconds
                     if (!Number.isNaN(span.endTimeUnixNano) && !Number.isNaN(span.startTimeUnixNano)) {
                         faroEventAttributes[DURATION_NS_KEY] = String(Number(span.endTimeUnixNano) - Number(span.startTimeUnixNano));

package/dist/cjs/exporters/faroTraceExporter.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"faroTraceExporter.utils.js","sourceRoot":"","sources":["../../../src/exporters/faroTraceExporter.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SpanContext } from '@opentelemetry/api';\nimport { ESpanKind, type IResourceSpans } from '@opentelemetry/otlp-transformer/build/src/trace/internal-types';\n\nimport { createInternalLogger, faro, unknownString } from '@grafana/faro-core';\nimport type { EventAttributes as FaroEventAttributes } from '@grafana/faro-core';\n\nconst internalLogger = createInternalLogger();\n\nconst DURATION_NS_KEY = 'duration_ns';\n\n/**\n * Send Faro events for CLIENT spans (HTTP requests, navigation, etc.)\n *\n * IMPORTANT: This function is called during trace export and must be careful to avoid infinite loops.\n *\n * Infinite loop prevention strategy:\n * 1. Only process SPAN_KIND_CLIENT spans (HTTP requests, etc.)\n * 2. Use faro.api.pushEvent which:\n *    - Does NOT trigger console logs if ConsoleInstrumentation is configured properly\n *    - Does NOT trigger HTTP instrumentation for collector URLs (they're ignored)\n * 3. Use internalLogger for debugging instead of console\n * 4. Never call console.log/warn/error in this function\n *\n * @param resourceSpans - OTLP resource spans from trace exporter\n */\nexport function sendFaroEvents(resourceSpans: IResourceSpans[] = []) {\n  try {\n    for (const resourceSpan of resourceSpans) {\n      const { scopeSpans } = resourceSpan;\n\n      for (const scopeSpan of scopeSpans) {\n        const { scope, spans = [] } = scopeSpan;\n\n        for (const span of spans) {\n          // Only process CLIENT spans (HTTP requests, external calls)\n          // This avoids processing internal spans which could cause loops\n          if (span.kind !== ESpanKind.SPAN_KIND_CLIENT) {\n            continue;\n          }\n\n          const spanContext: Pick<SpanContext, 'traceId' | 'spanId'> = {\n            traceId: span.traceId.toString(),\n            spanId: span.spanId.toString(),\n          };\n\n          const faroEventAttributes: FaroEventAttributes = {};\n          for (const attribute of span.attributes) {\n            faroEventAttributes[attribute.key] = String(Object.values(attribute.value)[0]);\n          }\n\n          // Add span duration in nanoseconds\n          if (!Number.isNaN(span.endTimeUnixNano) && !Number.isNaN(span.startTimeUnixNano)) {\n            faroEventAttributes[DURATION_NS_KEY] = String(\n              Number(span.endTimeUnixNano) - Number(span.startTimeUnixNano)\n            );\n          }\n\n          const index = (scope?.name ?? '').indexOf('-');\n          let eventName = unknownString;\n\n          if (scope?.name) {\n            if (index === -1) {\n              eventName = scope.name.split('/')[1] ?? scope.name;\n            }\n\n            if (index > -1) {\n              eventName = scope?.name.substring(index + 1);\n            }\n          }\n\n          // Push event to Faro\n          // This should NOT cause infinite loops because:\n          // 1. The collector URL is in ignoreUrls for HttpInstrumentation\n          // 2. ConsoleInstrumentation won't log this event\n          // 3. No console.log calls are made here\n          faro.api.pushEvent(`faro.tracing.${eventName}`, faroEventAttributes, undefined, {\n            spanContext,\n            // Convert nanoseconds to milliseconds\n            timestampOverwriteMs: Number(span.endTimeUnixNano) / 1_000_000,\n            customPayloadTransformer: (payload) => {\n              if (\n                faroEventAttributes['faro.action.user.name'] != null &&\n                faroEventAttributes['faro.action.user.parentId'] != null\n              ) {\n                payload.action = {\n                  name: faroEventAttributes['faro.action.user.name'],\n                  parentId: faroEventAttributes['faro.action.user.parentId'],\n                };\n\n                delete payload.attributes?.['faro.action.user.name'];\n                delete payload.attributes?.['faro.action.user.parentId'];\n              }\n\n              return payload;\n            },\n          });\n        }\n      }\n    }\n  } catch (error) {\n    // Only log critical errors using internal logger\n    // Do NOT use console.log here as it could cause infinite loops\n    internalLogger.error('sendFaroEvents: Failed to process spans', error);\n  }\n}\n"]}
+{"version":3,"file":"faroTraceExporter.utils.js","sourceRoot":"","sources":["../../../src/exporters/faroTraceExporter.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SpanContext } from '@opentelemetry/api';\nimport { ESpanKind, type IResourceSpans } from '@opentelemetry/otlp-transformer/build/src/trace/internal-types';\n\nimport { createInternalLogger, faro, unknownString } from '@grafana/faro-core';\nimport type { EventAttributes as FaroEventAttributes } from '@grafana/faro-core';\n\nconst internalLogger = createInternalLogger();\n\nconst DURATION_NS_KEY = 'duration_ns';\n/** Map stable OTel span attributes to Faro's fetch event contract. */\nfunction projectFetchEventAttributes(attributes: FaroEventAttributes): void {\n  const fields = {\n    'http.request.method': 'http.method',\n    'url.full': 'http.url',\n    'http.response.status_code': 'http.status_code',\n  };\n  for (const [spanField, eventField] of Object.entries(fields)) {\n    if (attributes[spanField] != null) {\n      attributes[eventField] = attributes[spanField];\n      delete attributes[spanField];\n    }\n  }\n\n  const url = attributes['http.url'];\n  if (url) {\n    try {\n      const parsed = new URL(url);\n      attributes['http.host'] = attributes['http.host'] ?? parsed.host;\n      attributes['http.scheme'] = attributes['http.scheme'] ?? parsed.protocol.replace(':', '');\n    } catch {\n      // Keep the captured URL even if it cannot supply host/scheme metadata.\n    }\n  }\n  delete attributes['server.address'];\n  delete attributes['server.port'];\n  attributes['component'] = attributes['component'] ?? 'fetch';\n}\n\n/**\n * Send Faro events for CLIENT spans (HTTP requests, navigation, etc.)\n *\n * IMPORTANT: This function is called during trace export and must be careful to avoid infinite loops.\n *\n * Infinite loop prevention strategy:\n * 1. Only process SPAN_KIND_CLIENT spans (HTTP requests, etc.)\n * 2. Use faro.api.pushEvent which:\n *    - Does NOT trigger console logs if ConsoleInstrumentation is configured properly\n *    - Does NOT trigger HTTP instrumentation for collector URLs (they're ignored)\n * 3. Use internalLogger for debugging instead of console\n * 4. Never call console.log/warn/error in this function\n *\n * @param resourceSpans - OTLP resource spans from trace exporter\n */\nexport function sendFaroEvents(resourceSpans: IResourceSpans[] = []) {\n  try {\n    for (const resourceSpan of resourceSpans) {\n      const { scopeSpans } = resourceSpan;\n\n      for (const scopeSpan of scopeSpans) {\n        const { scope, spans = [] } = scopeSpan;\n\n        for (const span of spans) {\n          // Only process CLIENT spans (HTTP requests, external calls)\n          // This avoids processing internal spans which could cause loops\n          if (span.kind !== ESpanKind.SPAN_KIND_CLIENT) {\n            continue;\n          }\n\n          const spanContext: Pick<SpanContext, 'traceId' | 'spanId'> = {\n            traceId: span.traceId.toString(),\n            spanId: span.spanId.toString(),\n          };\n\n          const faroEventAttributes: FaroEventAttributes = {};\n          for (const attribute of span.attributes) {\n            faroEventAttributes[attribute.key] = String(Object.values(attribute.value)[0]);\n          }\n\n          if (scope?.name === '@opentelemetry/instrumentation-fetch') {\n            projectFetchEventAttributes(faroEventAttributes);\n          }\n\n          // Add span duration in nanoseconds\n          if (!Number.isNaN(span.endTimeUnixNano) && !Number.isNaN(span.startTimeUnixNano)) {\n            faroEventAttributes[DURATION_NS_KEY] = String(\n              Number(span.endTimeUnixNano) - Number(span.startTimeUnixNano)\n            );\n          }\n\n          const index = (scope?.name ?? '').indexOf('-');\n          let eventName = unknownString;\n\n          if (scope?.name) {\n            if (index === -1) {\n              eventName = scope.name.split('/')[1] ?? scope.name;\n            }\n\n            if (index > -1) {\n              eventName = scope?.name.substring(index + 1);\n            }\n          }\n\n          // Push event to Faro\n          // This should NOT cause infinite loops because:\n          // 1. The collector URL is in ignoreUrls for HttpInstrumentation\n          // 2. ConsoleInstrumentation won't log this event\n          // 3. No console.log calls are made here\n          faro.api.pushEvent(`faro.tracing.${eventName}`, faroEventAttributes, undefined, {\n            spanContext,\n            // Convert nanoseconds to milliseconds\n            timestampOverwriteMs: Number(span.endTimeUnixNano) / 1_000_000,\n            customPayloadTransformer: (payload) => {\n              if (\n                faroEventAttributes['faro.action.user.name'] != null &&\n                faroEventAttributes['faro.action.user.parentId'] != null\n              ) {\n                payload.action = {\n                  name: faroEventAttributes['faro.action.user.name'],\n                  parentId: faroEventAttributes['faro.action.user.parentId'],\n                };\n\n                delete payload.attributes?.['faro.action.user.name'];\n                delete payload.attributes?.['faro.action.user.parentId'];\n              }\n\n              return payload;\n            },\n          });\n        }\n      }\n    }\n  } catch (error) {\n    // Only log critical errors using internal logger\n    // Do NOT use console.log here as it could cause infinite loops\n    internalLogger.error('sendFaroEvents: Failed to process spans', error);\n  }\n}\n"]}

package/dist/cjs/instrumentation.js

@@ -76,8 +76,34 @@ var faroMetaAttributesSpanProcessor_1 = require("./processors/faroMetaAttributes
 var httpRequestMonitorSpanProcessor_1 = require("./processors/httpRequestMonitorSpanProcessor");
 var semconv_1 = require("./semconv");
 var sampler_1 = require("./utils/sampler");
-// Import React Native TracerProvider
-// Note: We use the base provider since React Native doesn't have a specific one
+var detachedInstrumentations = new WeakSet();
+/**
+ * Keeps a caller-supplied processor reusable across Faro remove/add cycles.
+ * Explicit TracingInstrumentation.shutdown() remains responsible for the
+ * processor's terminal shutdown.
+ */
+var BorrowedSpanProcessor = /** @class */ (function () {
+    function BorrowedSpanProcessor(processor) {
+        this.processor = processor;
+    }
+    BorrowedSpanProcessor.prototype.forceFlush = function () {
+        return this.processor.forceFlush();
+    };
+    BorrowedSpanProcessor.prototype.onStart = function (span, parentContext) {
+        this.processor.onStart(span, parentContext);
+    };
+    BorrowedSpanProcessor.prototype.onEnding = function (span) {
+        var _a, _b;
+        (_b = (_a = this.processor).onEnding) === null || _b === void 0 ? void 0 : _b.call(_a, span);
+    };
+    BorrowedSpanProcessor.prototype.onEnd = function (span) {
+        this.processor.onEnd(span);
+    };
+    BorrowedSpanProcessor.prototype.shutdown = function () {
+        return Promise.resolve();
+    };
+    return BorrowedSpanProcessor;
+}());
 /**
  * TracingInstrumentation for React Native
  *
@@ -112,11 +138,13 @@ var TracingInstrumentation = /** @class */ (function (_super) {
         _this.options = options;
         _this.name = '@grafana/faro-react-native-tracing';
         _this.version = faro_core_1.VERSION;
+        _this.pendingShutdowns = new Set();
         return _this;
     }
     TracingInstrumentation.prototype.initialize = function () {
         var _this = this;
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e;
+        this.destroy();
         var options = this.options;
         var attributes = {};
         // App attributes
@@ -165,7 +193,7 @@ var TracingInstrumentation = /** @class */ (function (_super) {
         Object.assign(attributes, options.resourceAttributes);
         var resource = (0, resources_1.defaultResource)().merge((0, resources_1.resourceFromAttributes)(attributes));
         // Create tracer provider with span processors
-        this.provider = new sdk_trace_base_1.BasicTracerProvider({
+        var provider = new sdk_trace_base_1.BasicTracerProvider({
             resource: resource,
             sampler: {
                 shouldSample: function () {
@@ -175,51 +203,90 @@ var TracingInstrumentation = /** @class */ (function (_super) {
                 },
             },
             spanProcessors: [
-                (_b = options.spanProcessor) !== null && _b !== void 0 ? _b : new httpRequestMonitorSpanProcessor_1.HttpRequestMonitorSpanProcessor(new faroMetaAttributesSpanProcessor_1.FaroMetaAttributesSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(new faroTraceExporter_1.FaroTraceExporter({ api: this.api }), {
+                (_b = (options.spanProcessor && new BorrowedSpanProcessor(options.spanProcessor))) !== null && _b !== void 0 ? _b : new httpRequestMonitorSpanProcessor_1.HttpRequestMonitorSpanProcessor(new faroMetaAttributesSpanProcessor_1.FaroMetaAttributesSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(new faroTraceExporter_1.FaroTraceExporter({ api: this.api }), {
                     scheduledDelayMillis: TracingInstrumentation.SCHEDULED_BATCH_DELAY_MS,
                     maxExportBatchSize: 30,
                 }), this.metas)),
             ],
         });
-        // Register the provider as the global tracer provider
-        // This is CRITICAL for the tracer to generate real trace IDs instead of all zeros
-        api_1.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.
-        api_1.context.setGlobalContextManager((_c = options.contextManager) !== null && _c !== void 0 ? _c : new sdk_trace_web_1.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.
-        api_1.propagation.setGlobalPropagator((_d = options.propagator) !== null && _d !== void 0 ? _d : new core_1.CompositePropagator({
-            propagators: [new core_1.W3CTraceContextPropagator(), new core_1.W3CBaggagePropagator()],
-        }));
-        var _g = (_e = this.options.instrumentationOptions) !== null && _e !== void 0 ? _e : {}, enableFetchInstrumentation = _g.enableFetchInstrumentation, enableXhrInstrumentation = _g.enableXhrInstrumentation, propagateTraceHeaderCorsUrls = _g.propagateTraceHeaderCorsUrls, fetchInstrumentationOptions = _g.fetchInstrumentationOptions, xhrInstrumentationOptions = _g.xhrInstrumentationOptions;
-        // Get ignore URLs from transports to prevent infinite loops
-        var ignoreUrls = this.getIgnoreUrls();
-        // Register instrumentations
-        (0, instrumentation_1.registerInstrumentations)({
-            instrumentations: (_f = options.instrumentations) !== null && _f !== void 0 ? _f : (0, getDefaultOTELInstrumentations_1.getDefaultOTELInstrumentations)({
+        var registration = {
+            instrumentations: [],
+            ownsContextManager: false,
+            ownsContextManagerInstance: false,
+            ownsPropagator: false,
+            ownsTracerProvider: false,
+            provider: 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 (!api_1.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.
+            var contextManager = ((_c = options.contextManager) !== null && _c !== void 0 ? _c : new sdk_trace_web_1.StackContextManager()).enable();
+            registration.contextManager = contextManager;
+            registration.ownsContextManagerInstance = options.contextManager == null;
+            registration.ownsContextManager = api_1.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 = api_1.propagation.setGlobalPropagator((_d = options.propagator) !== null && _d !== void 0 ? _d : new core_1.CompositePropagator({
+                propagators: [new core_1.W3CTraceContextPropagator(), new core_1.W3CBaggagePropagator()],
+            }));
+            var _f = (_e = this.options.instrumentationOptions) !== null && _e !== void 0 ? _e : {}, enableFetchInstrumentation = _f.enableFetchInstrumentation, enableXhrInstrumentation = _f.enableXhrInstrumentation, propagateTraceHeaderCorsUrls = _f.propagateTraceHeaderCorsUrls, fetchInstrumentationOptions = _f.fetchInstrumentationOptions, xhrInstrumentationOptions = _f.xhrInstrumentationOptions;
+            // Get ignore URLs from transports to prevent infinite loops
+            var ignoreUrls = this.getIgnoreUrls();
+            var defaultInstrumentationOptions = {
                 ignoreUrls: ignoreUrls,
                 enableFetchInstrumentation: enableFetchInstrumentation,
                 enableXhrInstrumentation: enableXhrInstrumentation,
                 propagateTraceHeaderCorsUrls: propagateTraceHeaderCorsUrls,
                 fetchInstrumentationOptions: fetchInstrumentationOptions,
                 xhrInstrumentationOptions: 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
-        var globalFaroInstance = (0, faro_core_1.getInternalFaroFromGlobalObject)();
-        if (globalFaroInstance) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Extending Faro instance with OTEL API
-            globalFaroInstance.otel = {
-                trace: api_1.trace,
-                context: api_1.context,
             };
+            if (options.instrumentations) {
+                registration.instrumentations = options.instrumentations.flat();
+            }
+            else if (this.defaultInstrumentations) {
+                (0, getDefaultOTELInstrumentations_1.updateDefaultOTELInstrumentations)(this.defaultInstrumentations, defaultInstrumentationOptions);
+                registration.instrumentations = this.defaultInstrumentations;
+            }
+            else {
+                this.defaultInstrumentations = (0, getDefaultOTELInstrumentations_1.getDefaultOTELInstrumentations)(defaultInstrumentationOptions).flat();
+                registration.instrumentations = this.defaultInstrumentations;
+            }
+            var instrumentationsNeedingExplicitEnable = registration.instrumentations.filter(function (instrumentation) {
+                return detachedInstrumentations.has(instrumentation) && instrumentation.getConfig().enabled === true;
+            });
+            registration.unregisterInstrumentations = (0, instrumentation_1.registerInstrumentations)({
+                instrumentations: registration.instrumentations,
+            });
+            registration.instrumentations.forEach(function (instrumentation) {
+                detachedInstrumentations.delete(instrumentation);
+            });
+            instrumentationsNeedingExplicitEnable.forEach(function (instrumentation) { return 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
+            var globalFaroInstance = (0, faro_core_1.getInternalFaroFromGlobalObject)();
+            if (globalFaroInstance) {
+                var faroOtel = { trace: api_1.trace, context: api_1.context };
+                registration.faro = globalFaroInstance;
+                registration.faroOtel = faroOtel;
+                registration.previousFaroOtel = globalFaroInstance.otel;
+                globalFaroInstance.otel = faroOtel;
+            }
+        }
+        catch (error) {
+            this.destroy();
+            throw error;
         }
     };
     /**
@@ -244,24 +311,172 @@ var TracingInstrumentation = /** @class */ (function (_super) {
         // Return dev-server, original transport URLs, and regex patterns for maximum coverage.
         return __spreadArray(__spreadArray(__spreadArray([], (0, devServerIgnoreUrls_1.getReactNativeDevServerIgnoreUrls)(), true), transportUrls, true), regexPatterns, true);
     };
-    /**
-     * Shutdown the tracer provider
-     */
+    TracingInstrumentation.prototype.detachRegistration = function () {
+        var _this = this;
+        var registration = this.activeRegistration;
+        if (!registration) {
+            return undefined;
+        }
+        this.activeRegistration = undefined;
+        registration.instrumentations.forEach(function (instrumentation) { return detachedInstrumentations.add(instrumentation); });
+        var unregistered = false;
+        if (registration.unregisterInstrumentations) {
+            try {
+                registration.unregisterInstrumentations();
+                unregistered = true;
+            }
+            catch (error) {
+                this.logCleanupError('unregister OpenTelemetry instrumentations', error);
+            }
+        }
+        if (!unregistered) {
+            registration.instrumentations.forEach(function (instrumentation) {
+                _this.runCleanup("disable ".concat(instrumentation.instrumentationName), function () { return instrumentation.disable(); });
+            });
+        }
+        var faro = registration.faro, faroOtel = registration.faroOtel;
+        if (faro && faroOtel && faro.otel === faroOtel) {
+            this.runCleanup('restore faro.otel', function () {
+                if (registration.previousFaroOtel === undefined) {
+                    delete faro.otel;
+                }
+                else {
+                    faro.otel = registration.previousFaroOtel;
+                }
+            });
+        }
+        if (registration.ownsPropagator) {
+            this.runCleanup('clear the OpenTelemetry propagator', function () { return api_1.propagation.disable(); });
+        }
+        if (registration.ownsContextManager) {
+            this.runCleanup('clear the OpenTelemetry context manager', function () { return api_1.context.disable(); });
+        }
+        else if (registration.ownsContextManagerInstance && registration.contextManager) {
+            this.runCleanup('disable the unused OpenTelemetry context manager', function () { var _a; return (_a = registration.contextManager) === null || _a === void 0 ? void 0 : _a.disable(); });
+        }
+        if (registration.ownsTracerProvider) {
+            this.runCleanup('clear the OpenTelemetry tracer provider', function () { return api_1.trace.disable(); });
+        }
+        return registration;
+    };
+    TracingInstrumentation.prototype.runCleanup = function (action, cleanup) {
+        try {
+            cleanup();
+        }
+        catch (error) {
+            this.logCleanupError(action, error);
+        }
+    };
+    TracingInstrumentation.prototype.logCleanupError = function (action, error) {
+        try {
+            this.logError("Failed to ".concat(action, ":"), error);
+        }
+        catch (_loggingError) {
+            // Cleanup must not fail because a custom logger threw.
+        }
+    };
+    TracingInstrumentation.prototype.startProviderShutdown = function (registration) {
+        var _this = this;
+        if (!registration.shutdownPromise) {
+            var shutdownPromise_1 = Promise.resolve()
+                .then(function () { return registration.provider.forceFlush(); })
+                .catch(function (error) {
+                _this.logCleanupError('flush the OpenTelemetry tracer provider', error);
+            })
+                .then(function () { return registration.provider.shutdown(); });
+            registration.shutdownPromise = shutdownPromise_1;
+            this.pendingShutdowns.add(shutdownPromise_1);
+            void shutdownPromise_1.then(function () { return _this.pendingShutdowns.delete(shutdownPromise_1); }, function () { return _this.pendingShutdowns.delete(shutdownPromise_1); });
+        }
+        return registration.shutdownPromise;
+    };
+    TracingInstrumentation.prototype.startSuppliedSpanProcessorShutdown = function () {
+        var 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. */
     TracingInstrumentation.prototype.shutdown = function () {
         return __awaiter(this, void 0, void 0, function () {
+            var pendingShutdowns, registration, firstError, shutdownFailed, _i, pendingShutdowns_1, shutdownPromise, error_1, spanProcessorShutdown, error_2;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        if (!this.provider) return [3 /*break*/, 2];
-                        return [4 /*yield*/, this.provider.shutdown()];
+                        pendingShutdowns = Array.from(this.pendingShutdowns);
+                        registration = this.detachRegistration();
+                        if (registration) {
+                            pendingShutdowns.push(this.startProviderShutdown(registration));
+                        }
+                        shutdownFailed = false;
+                        _i = 0, pendingShutdowns_1 = pendingShutdowns;
+                        _a.label = 1;
                     case 1:
-                        _a.sent();
+                        if (!(_i < pendingShutdowns_1.length)) return [3 /*break*/, 6];
+                        shutdownPromise = pendingShutdowns_1[_i];
                         _a.label = 2;
-                    case 2: return [2 /*return*/];
+                    case 2:
+                        _a.trys.push([2, 4, , 5]);
+                        return [4 /*yield*/, shutdownPromise];
+                    case 3:
+                        _a.sent();
+                        return [3 /*break*/, 5];
+                    case 4:
+                        error_1 = _a.sent();
+                        if (!shutdownFailed) {
+                            firstError = error_1;
+                            shutdownFailed = true;
+                        }
+                        return [3 /*break*/, 5];
+                    case 5:
+                        _i++;
+                        return [3 /*break*/, 1];
+                    case 6:
+                        spanProcessorShutdown = this.startSuppliedSpanProcessorShutdown();
+                        if (!spanProcessorShutdown) return [3 /*break*/, 10];
+                        _a.label = 7;
+                    case 7:
+                        _a.trys.push([7, 9, , 10]);
+                        return [4 /*yield*/, spanProcessorShutdown];
+                    case 8:
+                        _a.sent();
+                        return [3 /*break*/, 10];
+                    case 9:
+                        error_2 = _a.sent();
+                        if (!shutdownFailed) {
+                            firstError = error_2;
+                            shutdownFailed = true;
+                        }
+                        return [3 /*break*/, 10];
+                    case 10:
+                        if (shutdownFailed) {
+                            throw firstError;
+                        }
+                        return [2 /*return*/];
                 }
             });
         });
     };
+    /** Detach synchronously when Faro removes this instrumentation. */
+    TracingInstrumentation.prototype.destroy = function () {
+        var _this = this;
+        var registration = this.detachRegistration();
+        if (!registration) {
+            return;
+        }
+        void this.startProviderShutdown(registration).then(undefined, function (error) {
+            _this.logCleanupError('shut down the OpenTelemetry tracer provider', error);
+        });
+    };
     TracingInstrumentation.SCHEDULED_BATCH_DELAY_MS = 1000;
     return TracingInstrumentation;
 }(faro_core_1.BaseInstrumentation));