@grafana/faro-react-native-tracing 1.0.0-alpha.1

package/src/instrumentation.ts

@@ -0,0 +1,241 @@
+import { context, trace } from '@opentelemetry/api';
+import type { Attributes } from '@opentelemetry/api';
+import { registerInstrumentations } 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 {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+  SEMRESATTRS_DEPLOYMENT_ENVIRONMENT,
+} from '@opentelemetry/semantic-conventions';
+
+import { BaseInstrumentation, getInternalFaroFromGlobalObject, VERSION } from '@grafana/faro-core';
+import type { Transport } from '@grafana/faro-core';
+
+import { FaroTraceExporter } from './exporters/faroTraceExporter';
+import { getDefaultOTELInstrumentations } from './instrumentations/getDefaultOTELInstrumentations';
+import { FaroMetaAttributesSpanProcessor } from './processors/faroMetaAttributesSpanProcessor';
+import { HttpRequestMonitorSpanProcessor } from './processors/httpRequestMonitorSpanProcessor';
+import {
+  ATTR_APP_VERSION,
+  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
+  ATTR_DEVICE_BRAND,
+  ATTR_DEVICE_LOCALE,
+  ATTR_DEVICE_MODEL,
+  ATTR_DEVICE_OS_VERSION,
+  ATTR_DEVICE_PLATFORM,
+  ATTR_PROCESS_RUNTIME_NAME,
+  ATTR_PROCESS_RUNTIME_VERSION,
+  ATTR_SERVICE_NAMESPACE,
+  ATTR_TELEMETRY_DISTRO_NAME,
+  ATTR_TELEMETRY_DISTRO_VERSION,
+} from './semconv';
+import type { TracingInstrumentationOptions } from './types';
+import { getSamplingDecision } from './utils/sampler';
+
+// Import React Native TracerProvider
+// Note: We use the base provider since React Native doesn't have a specific one
+
+/**
+ * TracingInstrumentation for React Native
+ *
+ * Enables distributed tracing with OpenTelemetry for React Native applications.
+ *
+ * IMPORTANT: Infinite loop prevention
+ * - Uses internalLogger for debugging instead of console
+ * - Collector URLs are added to ignoreUrls in HTTP instrumentation
+ * - BatchSpanProcessor delays span export to avoid blocking
+ * - No console logging during trace export
+ *
+ * Example usage:
+ * ```ts
+ * import { initializeFaro } from '@grafana/faro-react-native';
+ * import { TracingInstrumentation } from '@grafana/faro-react-native-tracing';
+ *
+ * initializeFaro({
+ *   // ... other config
+ *   instrumentations: [
+ *     new TracingInstrumentation({
+ *       propagateTraceHeaderCorsUrls: [/https:\\/\\/my-api\\.com/],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class TracingInstrumentation extends BaseInstrumentation {
+  name = '@grafana/faro-react-native-tracing';
+  version = VERSION;
+
+  static SCHEDULED_BATCH_DELAY_MS = 1000;
+
+  private provider?: BasicTracerProvider;
+
+  constructor(private options: TracingInstrumentationOptions = {}) {
+    super();
+  }
+
+  initialize(): void {
+    const options = this.options;
+    const attributes: Attributes = {};
+
+    // App attributes
+    if (this.config.app.name) {
+      attributes[ATTR_SERVICE_NAME] = this.config.app.name;
+    }
+
+    if (this.config.app.namespace) {
+      attributes[ATTR_SERVICE_NAMESPACE] = this.config.app.namespace;
+    }
+
+    if (this.config.app.version) {
+      attributes[ATTR_SERVICE_VERSION] = this.config.app.version;
+      attributes[ATTR_APP_VERSION] = this.config.app.version;
+    }
+
+    if (this.config.app.environment) {
+      attributes[ATTR_DEPLOYMENT_ENVIRONMENT_NAME] = this.config.app.environment;
+
+      /**
+       * @deprecated will be removed in the future and has been replaced by ATTR_DEPLOYMENT_ENVIRONMENT_NAME (deployment.environment.name)
+       * We need to keep this for compatibility with some internal services for now.
+       */
+      attributes[SEMRESATTRS_DEPLOYMENT_ENVIRONMENT] = this.config.app.environment;
+    }
+
+    // Device/Platform attributes from React Native
+    // Note: metas.value contains all meta providers, we need to check if device meta exists
+    const allMetas = this.metas.value as Record<string, unknown>;
+    const deviceMeta = allMetas['device'] as
+      | {
+          model?: string;
+          brand?: string;
+          osName?: string;
+          osVersion?: string;
+          locale?: string;
+        }
+      | undefined;
+
+    if (deviceMeta?.model) {
+      attributes[ATTR_DEVICE_MODEL] = deviceMeta.model;
+    }
+
+    if (deviceMeta?.brand) {
+      attributes[ATTR_DEVICE_BRAND] = deviceMeta.brand;
+    }
+
+    if (deviceMeta?.osName) {
+      attributes[ATTR_DEVICE_PLATFORM] = deviceMeta.osName;
+    }
+
+    if (deviceMeta?.osVersion) {
+      attributes[ATTR_DEVICE_OS_VERSION] = deviceMeta.osVersion;
+    }
+
+    if (deviceMeta?.locale) {
+      attributes[ATTR_DEVICE_LOCALE] = deviceMeta.locale;
+    }
+
+    attributes[ATTR_PROCESS_RUNTIME_NAME] = 'react-native';
+    attributes[ATTR_PROCESS_RUNTIME_VERSION] = deviceMeta?.osVersion ?? 'unknown';
+
+    attributes[ATTR_TELEMETRY_DISTRO_NAME] = 'faro-react-native-sdk';
+    attributes[ATTR_TELEMETRY_DISTRO_VERSION] = VERSION;
+
+    // Merge with user-provided attributes
+    Object.assign(attributes, options.resourceAttributes);
+
+    const resource = defaultResource().merge(resourceFromAttributes(attributes));
+
+    // Create tracer provider with span processors
+    this.provider = new ReactNativeTracerProvider({
+      resource,
+      sampler: {
+        shouldSample: () => {
+          return {
+            decision: getSamplingDecision(this.api.getSession()),
+          };
+        },
+      },
+      spanProcessors: [
+        options.spanProcessor ??
+          new HttpRequestMonitorSpanProcessor(
+            new FaroMetaAttributesSpanProcessor(
+              new BatchSpanProcessor(new 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
+    trace.setGlobalTracerProvider(this.provider);
+
+    const { 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,
+          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,
+      };
+    }
+  }
+
+  /**
+   * Get ignore URLs from all transports to avoid tracing collector requests
+   * CRITICAL: This prevents infinite loops where trace exports trigger more traces
+   */
+  private getIgnoreUrls(): Array<string | RegExp> {
+    // Get URLs from transports' getIgnoreUrls() method
+    const transportUrls = this.transports.transports.flatMap((transport: Transport) => {
+      return transport.getIgnoreUrls();
+    });
+
+    // Create regex patterns that match both with and without trailing slashes
+    // This is critical because fetch() might add trailing slashes
+    const regexPatterns = transportUrls.map((url) => {
+      if (typeof url === 'string') {
+        // Escape special regex characters and make trailing slash optional
+        const escapedUrl = url.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`^${escapedUrl}/?$`);
+      }
+      return url;
+    });
+
+    // Return both original URLs and regex patterns for maximum coverage
+    return [...transportUrls, ...regexPatterns];
+  }
+
+  /**
+   * Shutdown the tracer provider
+   */
+  async shutdown(): Promise<void> {
+    if (this.provider) {
+      await this.provider.shutdown();
+    }
+  }
+}

package/src/instrumentations/getDefaultOTELInstrumentations.test.ts

@@ -0,0 +1,70 @@
+import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
+import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
+
+import { getDefaultOTELInstrumentations } from './getDefaultOTELInstrumentations';
+
+describe('getDefaultOTELInstrumentations', () => {
+  it('should return an array with FetchInstrumentation and XMLHttpRequestInstrumentation', () => {
+    const instrumentations = getDefaultOTELInstrumentations();
+
+    expect(instrumentations).toHaveLength(2);
+    expect(instrumentations[0]).toBeInstanceOf(FetchInstrumentation);
+    expect(instrumentations[1]).toBeInstanceOf(XMLHttpRequestInstrumentation);
+  });
+
+  it('should configure ignoreUrls', () => {
+    const ignoreUrls = [/test-url/];
+    const instrumentations = getDefaultOTELInstrumentations({ ignoreUrls });
+
+    expect(instrumentations).toHaveLength(2);
+    // FetchInstrumentation should have ignoreUrls configured
+    expect((instrumentations[0] as any)._config.ignoreUrls).toEqual(ignoreUrls);
+    // XMLHttpRequestInstrumentation should have ignoreUrls configured
+    expect((instrumentations[1] as any)._config.ignoreUrls).toEqual(ignoreUrls);
+  });
+
+  it('should set ignoreNetworkEvents to true by default', () => {
+    const instrumentations = getDefaultOTELInstrumentations();
+
+    expect((instrumentations[0] as any)._config.ignoreNetworkEvents).toBe(true);
+  });
+
+  it('should allow overriding ignoreNetworkEvents', () => {
+    const instrumentations = getDefaultOTELInstrumentations({
+      fetchInstrumentationOptions: {
+        ignoreNetworkEvents: false,
+      },
+    });
+
+    expect((instrumentations[0] as any)._config.ignoreNetworkEvents).toBe(false);
+  });
+
+  it('should configure propagateTraceHeaderCorsUrls', () => {
+    const propagateUrls = [/api\.example\.com/];
+    const instrumentations = getDefaultOTELInstrumentations({
+      propagateTraceHeaderCorsUrls: propagateUrls,
+    });
+
+    expect((instrumentations[0] as any)._config.propagateTraceHeaderCorsUrls).toEqual(propagateUrls);
+  });
+
+  it('should apply custom attribute function', () => {
+    const customFn = jest.fn();
+    const instrumentations = getDefaultOTELInstrumentations({
+      fetchInstrumentationOptions: {
+        applyCustomAttributesOnSpan: customFn,
+      },
+    });
+
+    expect(instrumentations).toHaveLength(2);
+    // Custom function should be wrapped by our defaults
+    expect((instrumentations[0] as any)._config.applyCustomAttributesOnSpan).toBeDefined();
+  });
+
+  it('should have a requestHook defined', () => {
+    const instrumentations = getDefaultOTELInstrumentations();
+
+    expect((instrumentations[0] as any)._config.requestHook).toBeDefined();
+    expect(typeof (instrumentations[0] as any)._config.requestHook).toBe('function');
+  });
+});

package/src/instrumentations/getDefaultOTELInstrumentations.ts

@@ -0,0 +1,83 @@
+import type { Span } from '@opentelemetry/api';
+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 {
+  fetchCustomAttributeFunctionWithDefaults,
+  xhrCustomAttributeFunctionWithDefaults,
+} from './instrumentationUtils';
+
+/**
+ * Get default OTEL instrumentations for React Native
+ *
+ * This function creates the default OpenTelemetry instrumentations for React Native:
+ * - FetchInstrumentation: Traces fetch() API calls
+ * - XMLHttpRequestInstrumentation: Traces XMLHttpRequest and axios (which uses XHR)
+ *
+ * IMPORTANT: Infinite loop prevention
+ * - ignoreUrls is used to exclude Faro collector URLs
+ * - ignoreNetworkEvents is true to avoid duplicate events
+ * - No console logging during instrumentation
+ *
+ * @param options - Configuration options
+ * @returns Array of OTEL instrumentations
+ */
+export function getDefaultOTELInstrumentations(options: DefaultInstrumentationsOptions = {}): InstrumentationOption[] {
+  const { fetchInstrumentationOptions, xhrInstrumentationOptions, ...sharedOptions } = options;
+
+  const fetchOpts = createFetchInstrumentationOptions(fetchInstrumentationOptions, sharedOptions);
+  const xhrOpts = createXhrInstrumentationOptions(xhrInstrumentationOptions, sharedOptions);
+
+  return [new FetchInstrumentation(fetchOpts), new XMLHttpRequestInstrumentation(xhrOpts)];
+}
+
+function createFetchInstrumentationOptions(
+  fetchInstrumentationOptions: DefaultInstrumentationsOptions['fetchInstrumentationOptions'],
+  sharedOptions: Record<string, unknown>
+) {
+  return {
+    ...sharedOptions,
+    // Ignore network performance events to avoid duplicates
+    ignoreNetworkEvents: true,
+    // Keep this here to overwrite the defaults above if provided by the users
+    ...fetchInstrumentationOptions,
+    // 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
+      }
+    },
+  };
+}
+
+function createXhrInstrumentationOptions(
+  xhrInstrumentationOptions: DefaultInstrumentationsOptions['xhrInstrumentationOptions'],
+  sharedOptions: Record<string, unknown>
+) {
+  return {
+    ...sharedOptions,
+    ignoreNetworkEvents: true,
+    ...xhrInstrumentationOptions,
+    applyCustomAttributesOnSpan: xhrCustomAttributeFunctionWithDefaults(
+      xhrInstrumentationOptions?.applyCustomAttributesOnSpan
+    ),
+  };
+}

package/src/instrumentations/instrumentationUtils.test.ts

@@ -0,0 +1,107 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+
+import { fetchCustomAttributeFunctionWithDefaults, setSpanStatusOnFetchError } from './instrumentationUtils';
+
+describe('instrumentationUtils', () => {
+  let provider: BasicTracerProvider;
+
+  beforeEach(() => {
+    provider = new BasicTracerProvider();
+  });
+
+  describe('setSpanStatusOnFetchError', () => {
+    it('should set span status to ERROR with error message', () => {
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const setStatusSpy = jest.spyOn(span, 'setStatus');
+      const error = new Error('Test error');
+
+      setSpanStatusOnFetchError(span, error);
+
+      expect(setStatusSpy).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Test error',
+      });
+    });
+
+    it('should set span status to ERROR with string message', () => {
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const setStatusSpy = jest.spyOn(span, 'setStatus');
+
+      setSpanStatusOnFetchError(span, 'String error message');
+
+      expect(setStatusSpy).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'String error message',
+      });
+    });
+  });
+
+  describe('fetchCustomAttributeFunctionWithDefaults', () => {
+    it('should call user function if provided', () => {
+      const userFunction = jest.fn();
+      const fn = fetchCustomAttributeFunctionWithDefaults(userFunction);
+
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const request = new Request('https://example.com');
+      const response = new Response();
+
+      fn(span, request, response);
+
+      expect(userFunction).toHaveBeenCalledWith(span, request, response);
+    });
+
+    it('should set error status when result is an Error', () => {
+      const fn = fetchCustomAttributeFunctionWithDefaults();
+
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const setStatusSpy = jest.spyOn(span, 'setStatus');
+      const request = new Request('https://example.com');
+      const error = new Error('Fetch failed');
+
+      fn(span, request, error as any);
+
+      expect(setStatusSpy).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Fetch failed',
+      });
+    });
+
+    it('should not set error status for successful Response', () => {
+      const fn = fetchCustomAttributeFunctionWithDefaults();
+
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const setStatusSpy = jest.spyOn(span, 'setStatus');
+      const request = new Request('https://example.com');
+      const response = new Response();
+
+      fn(span, request, response);
+
+      expect(setStatusSpy).not.toHaveBeenCalled();
+    });
+
+    it('should work with both user function and default error handling', () => {
+      const userFunction = jest.fn();
+      const fn = fetchCustomAttributeFunctionWithDefaults(userFunction);
+
+      const tracer = provider.getTracer('test');
+      const span = tracer.startSpan('test-span');
+      const setStatusSpy = jest.spyOn(span, 'setStatus');
+      const request = new Request('https://example.com');
+      const error = new Error('Combined test error');
+
+      fn(span, request, error as any);
+
+      expect(userFunction).toHaveBeenCalledWith(span, request, error);
+      expect(setStatusSpy).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Combined test error',
+      });
+    });
+  });
+});

package/src/instrumentations/instrumentationUtils.ts

@@ -0,0 +1,106 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { Span } from '@opentelemetry/api';
+import type { FetchCustomAttributeFunction } from '@opentelemetry/instrumentation-fetch';
+import type { XHRCustomAttributeFunction } from '@opentelemetry/instrumentation-xml-http-request';
+
+import { faro, type UserActionInternalInterface, UserActionState } from '@grafana/faro-core';
+
+/**
+ * FetchError interface matching OpenTelemetry's internal type
+ * Note: FetchError is not exported from @opentelemetry/instrumentation-fetch
+ */
+interface FetchError {
+  status?: number;
+  message: string;
+}
+
+/**
+ * Set span status to ERROR when fetch fails
+ *
+ * This ensures that failed HTTP requests are marked as errors in traces.
+ */
+export function setSpanStatusOnFetchError(span: Span, error: Error | string): void {
+  const message = typeof error === 'string' ? error : error.message;
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message,
+  });
+}
+
+/**
+ * Type guard to check if result is a FetchError
+ */
+function isFetchError(result: Response | FetchError): result is FetchError {
+  return 'message' in result && typeof (result as FetchError).message === 'string';
+}
+
+/**
+ * Custom attribute function for fetch instrumentation with defaults
+ *
+ * Combines user-provided custom attributes with default handling.
+ *
+ * @param userFunction - Optional user-provided custom attribute function
+ * @returns Combined custom attribute function
+ */
+export function fetchCustomAttributeFunctionWithDefaults(
+  userFunction?: FetchCustomAttributeFunction
+): FetchCustomAttributeFunction {
+  const fn: FetchCustomAttributeFunction = (
+    span: Span,
+    request: Request | RequestInit,
+    result: Response | FetchError
+  ) => {
+    // Call user function first if provided
+    if (userFunction) {
+      userFunction(span, request, result);
+    }
+
+    // Add default error handling
+    if (isFetchError(result)) {
+      setSpanStatusOnFetchError(span, result.message);
+    } else if (result instanceof Response && result.status >= 400 && result.status < 600) {
+      setSpanStatusOnFetchError(span, `HTTP ${result.status}: ${result.statusText}`);
+    }
+  };
+  return fn;
+}
+
+/**
+ * Set span status to ERROR for XHR failures (status 0 or 4xx/5xx).
+ */
+export function setSpanStatusOnXMLHttpRequestError(span: Span, xhr: XMLHttpRequest): void {
+  const status = xhr.status;
+  if (status == null) return;
+  if (status === 0 || (status >= 400 && status < 600)) {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+  }
+}
+
+/**
+ * Add user action context to span when active (for HTTP Errors column in user action table).
+ */
+function addUserActionContextToSpan(span: Span): void {
+  try {
+    const currentAction = faro.api?.getActiveUserAction?.();
+    const state = (currentAction as unknown as UserActionInternalInterface)?.getState?.();
+    if (currentAction && (state === UserActionState.Started || state === UserActionState.Halted)) {
+      span.setAttribute('faro.action.user.name', currentAction.name);
+      span.setAttribute('faro.action.user.parentId', currentAction.parentId);
+    }
+  } catch (_) {
+    // Silently fail - don't log to avoid instrumentation loops
+  }
+}
+
+/**
+ * Custom attribute function for XHR instrumentation with defaults.
+ */
+export function xhrCustomAttributeFunctionWithDefaults(
+  userFunction?: XHRCustomAttributeFunction
+): XHRCustomAttributeFunction {
+  return (span: Span, xhr: XMLHttpRequest) => {
+    setSpanStatusOnXMLHttpRequestError(span, xhr);
+    addUserActionContextToSpan(span);
+    userFunction?.(span, xhr);
+  };
+}