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

package/src/processors/faroMetaAttributesSpanProcessor.test.ts

@@ -0,0 +1,127 @@
+import { ROOT_CONTEXT } from '@opentelemetry/api';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+
+import type { Metas } from '@grafana/faro-core';
+
+import { FaroMetaAttributesSpanProcessor } from './faroMetaAttributesSpanProcessor';
+
+describe('FaroMetaAttributesSpanProcessor', () => {
+  let provider: BasicTracerProvider;
+  let mockProcessor: any;
+  let mockMetas: Metas;
+
+  beforeEach(() => {
+    provider = new BasicTracerProvider();
+    mockProcessor = {
+      forceFlush: jest.fn().mockResolvedValue(undefined),
+      onStart: jest.fn(),
+      onEnd: jest.fn(),
+      shutdown: jest.fn().mockResolvedValue(undefined),
+    };
+
+    mockMetas = {
+      value: {
+        session: {
+          id: 'test-session-id',
+        },
+        user: {
+          id: 'test-user-id',
+          email: 'test@example.com',
+          username: 'testuser',
+          fullName: 'Test User',
+          roles: 'admin, user',
+          hash: 'test-hash',
+        },
+      },
+      add: jest.fn(),
+      remove: jest.fn(),
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+    };
+  });
+
+  it('should add session ID to span attributes', () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+
+    processor.onStart(span as any, ROOT_CONTEXT);
+
+    expect((span as any).attributes['session.id']).toBe('test-session-id');
+  });
+
+  it('should add user attributes to span', () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+
+    processor.onStart(span as any, ROOT_CONTEXT);
+
+    expect((span as any).attributes['user.id']).toBe('test-user-id');
+    expect((span as any).attributes['user.email']).toBe('test@example.com');
+    expect((span as any).attributes['user.name']).toBe('testuser');
+    expect((span as any).attributes['user.full_name']).toBe('Test User');
+    expect((span as any).attributes['user.hash']).toBe('test-hash');
+  });
+
+  it('should parse and add user roles as array', () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+
+    processor.onStart(span as any, ROOT_CONTEXT);
+
+    expect((span as any).attributes['user.roles']).toEqual(['admin', 'user']);
+  });
+
+  it('should handle missing session gracefully', () => {
+    mockMetas.value = { user: mockMetas.value.user };
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+
+    processor.onStart(span as any, ROOT_CONTEXT);
+
+    expect((span as any).attributes['session.id']).toBeUndefined();
+    expect((span as any).attributes['user.id']).toBe('test-user-id');
+  });
+
+  it('should handle missing user gracefully', () => {
+    mockMetas.value = { session: mockMetas.value.session };
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+
+    processor.onStart(span as any, ROOT_CONTEXT);
+
+    expect((span as any).attributes['session.id']).toBe('test-session-id');
+    expect((span as any).attributes['user.id']).toBeUndefined();
+  });
+
+  it('should delegate onEnd to wrapped processor', () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span', {}, ROOT_CONTEXT);
+    span.end();
+
+    processor.onEnd(span as any);
+
+    expect(mockProcessor.onEnd).toHaveBeenCalledWith(span);
+  });
+
+  it('should delegate forceFlush to wrapped processor', async () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+
+    await processor.forceFlush();
+
+    expect(mockProcessor.forceFlush).toHaveBeenCalled();
+  });
+
+  it('should delegate shutdown to wrapped processor', async () => {
+    const processor = new FaroMetaAttributesSpanProcessor(mockProcessor, mockMetas);
+
+    await processor.shutdown();
+
+    expect(mockProcessor.shutdown).toHaveBeenCalled();
+  });
+});

package/src/processors/faroMetaAttributesSpanProcessor.ts

@@ -0,0 +1,71 @@
+import type { Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+import type { Metas } from '@grafana/faro-core';
+
+import { ATTR_SESSION_ID } from '../semconv';
+
+/**
+ * Span processor that adds Faro meta attributes to spans
+ *
+ * This processor enriches spans with:
+ * - Session ID
+ * - User information (email, id, username, etc.)
+ *
+ * IMPORTANT: This processor delegates to a wrapped processor and does NOT log
+ * to avoid infinite loops.
+ */
+export class FaroMetaAttributesSpanProcessor implements SpanProcessor {
+  constructor(
+    private processor: SpanProcessor,
+    private metas: Metas
+  ) {}
+
+  forceFlush(): Promise<void> {
+    return this.processor.forceFlush();
+  }
+
+  onStart(span: Span, parentContext: Context): void {
+    const session = this.metas.value.session;
+
+    if (session?.id) {
+      span.attributes[ATTR_SESSION_ID] = session.id;
+    }
+
+    const user = this.metas.value.user ?? {};
+
+    if (user.email) {
+      span.attributes['user.email'] = user.email;
+    }
+
+    if (user.id) {
+      span.attributes['user.id'] = user.id;
+    }
+
+    if (user.username) {
+      span.attributes['user.name'] = user.username;
+    }
+
+    if (user.fullName) {
+      span.attributes['user.full_name'] = user.fullName;
+    }
+
+    if (user.roles) {
+      span.attributes['user.roles'] = user.roles.split(',').map((role) => role.trim());
+    }
+
+    if (user.hash) {
+      span.attributes['user.hash'] = user.hash;
+    }
+
+    this.processor.onStart(span, parentContext);
+  }
+
+  onEnd(span: ReadableSpan): void {
+    this.processor.onEnd(span);
+  }
+
+  shutdown(): Promise<void> {
+    return this.processor.shutdown();
+  }
+}

package/src/processors/httpRequestMonitorSpanProcessor.ts

@@ -0,0 +1,106 @@
+import type { Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+import {
+  type HttpRequestMessagePayload,
+  notifyHttpRequestEnd,
+  notifyHttpRequestStart,
+} from '@grafana/faro-react-native';
+
+const ATTR_HTTP_METHOD = 'http.method';
+const ATTR_HTTP_STATUS_CODE = 'http.status_code';
+const ATTR_HTTP_URL = 'http.url';
+
+/**
+ * Get string attribute from span.
+ * Handles both SDK attribute format and OTLP-style attribute values.
+ */
+function getAttr(span: Span | ReadableSpan, key: string): string | undefined {
+  const attrs = span.attributes as Record<string, unknown> | undefined;
+  if (attrs == null) return undefined;
+  const raw = typeof attrs['get'] === 'function' ? (attrs as { get: (k: string) => unknown })['get'](key) : attrs[key];
+  if (raw == null) return undefined;
+  if (typeof raw === 'string') return raw.length > 0 ? raw : undefined;
+  if (typeof raw === 'object' && raw !== null && 'stringValue' in raw) {
+    const s = String((raw as { stringValue?: string }).stringValue ?? '');
+    return s.length > 0 ? s : undefined;
+  }
+  const str = String(raw);
+  return str.length > 0 ? str : undefined;
+}
+
+/**
+ * Check if a span is an HTTP span (from FetchInstrumentation).
+ */
+function isHttpSpan(span: Span | ReadableSpan): boolean {
+  return getAttr(span, ATTR_HTTP_URL) != null || getAttr(span, ATTR_HTTP_METHOD) != null;
+}
+
+/**
+ * SpanProcessor that notifies httpRequestMonitor when HTTP spans start and end.
+ *
+ * This enables user action correlation (UserActionController halt logic) when
+ * TracingInstrumentation is used instead of HttpInstrumentation.
+ *
+ * IMPORTANT: Must not use console or trigger any instrumentation to avoid loops.
+ */
+export class HttpRequestMonitorSpanProcessor implements SpanProcessor {
+  constructor(private readonly processor: SpanProcessor) {}
+
+  onStart(span: Span, parentContext: Context): void {
+    if (isHttpSpan(span)) {
+      const url = getAttr(span, ATTR_HTTP_URL) ?? '';
+      const method = getAttr(span, ATTR_HTTP_METHOD) ?? 'GET';
+      const requestId = span.spanContext().spanId;
+      const startTimeMs = Date.now();
+
+      const payload: HttpRequestMessagePayload = {
+        requestId,
+        url,
+        method,
+        startTime: startTimeMs,
+      };
+      notifyHttpRequestStart(payload);
+    }
+
+    this.processor.onStart(span, parentContext);
+  }
+
+  onEnd(span: ReadableSpan): void {
+    if (isHttpSpan(span)) {
+      const url = getAttr(span, ATTR_HTTP_URL) ?? '';
+      const method = getAttr(span, ATTR_HTTP_METHOD) ?? 'GET';
+      const requestId = span.spanContext().spanId;
+      const statusAttr = getAttr(span, ATTR_HTTP_STATUS_CODE);
+      const status = statusAttr != null ? parseInt(statusAttr, 10) : undefined;
+      const spanWithTime = span as ReadableSpan & {
+        startTimeUnixNano?: number | bigint;
+        endTimeUnixNano?: number | bigint;
+      };
+      const startNs = spanWithTime.startTimeUnixNano;
+      const endNs = spanWithTime.endTimeUnixNano;
+      const startTimeMs = startNs != null && !Number.isNaN(Number(startNs)) ? Number(startNs) / 1_000_000 : Date.now();
+      const endTimeMs = endNs != null && !Number.isNaN(Number(endNs)) ? Number(endNs) / 1_000_000 : Date.now();
+
+      const payload: HttpRequestMessagePayload = {
+        requestId,
+        url,
+        method,
+        startTime: startTimeMs,
+        endTime: endTimeMs,
+        status: !Number.isNaN(status) ? status : undefined,
+      };
+      notifyHttpRequestEnd(payload);
+    }
+
+    this.processor.onEnd(span);
+  }
+
+  forceFlush(): Promise<void> {
+    return this.processor.forceFlush();
+  }
+
+  shutdown(): Promise<void> {
+    return this.processor.shutdown();
+  }
+}

package/src/semconv.ts

@@ -0,0 +1,31 @@
+/**
+ * Semantic convention attributes for React Native tracing
+ * Based on OpenTelemetry semantic conventions with React Native-specific additions
+ */
+
+// Session attributes
+export const ATTR_SESSION_ID = 'session.id';
+
+// Device/Platform attributes for React Native
+export const ATTR_DEVICE_MODEL = 'device.model';
+export const ATTR_DEVICE_BRAND = 'device.brand';
+export const ATTR_DEVICE_PLATFORM = 'device.platform';
+export const ATTR_DEVICE_OS_VERSION = 'device.os.version';
+export const ATTR_DEVICE_TYPE = 'device.type';
+export const ATTR_DEVICE_LOCALE = 'device.locale';
+
+// App attributes
+export const ATTR_APP_VERSION = 'app.version';
+export const ATTR_APP_BUILD = 'app.build';
+
+// Service attributes
+export const ATTR_SERVICE_NAMESPACE = 'service.namespace';
+export const ATTR_DEPLOYMENT_ENVIRONMENT_NAME = 'deployment.environment.name';
+
+// Telemetry attributes
+export const ATTR_TELEMETRY_DISTRO_NAME = 'telemetry.distro.name';
+export const ATTR_TELEMETRY_DISTRO_VERSION = 'telemetry.distro.version';
+
+// Process/Runtime attributes
+export const ATTR_PROCESS_RUNTIME_NAME = 'process.runtime.name';
+export const ATTR_PROCESS_RUNTIME_VERSION = 'process.runtime.version';

package/src/types.ts

@@ -0,0 +1,39 @@
+import type { Attributes, ContextManager, TextMapPropagator } from '@opentelemetry/api';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+import type { FetchCustomAttributeFunction } from '@opentelemetry/instrumentation-fetch';
+import type { XHRCustomAttributeFunction } from '@opentelemetry/instrumentation-xml-http-request';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+import type { API, Patterns } from '@grafana/faro-core';
+
+export type InstrumentationOption = Instrumentation | Instrumentation[];
+
+export interface FaroTraceExporterConfig {
+  api: API;
+}
+
+export interface TracingInstrumentationOptions {
+  resourceAttributes?: Attributes;
+  propagator?: TextMapPropagator;
+  contextManager?: ContextManager;
+  instrumentations?: InstrumentationOption[];
+  spanProcessor?: SpanProcessor;
+  instrumentationOptions?: Omit<DefaultInstrumentationsOptions, 'ignoreUrls'>;
+}
+
+export type MatchUrlDefinitions = Patterns;
+
+export type DefaultInstrumentationsOptions = {
+  ignoreUrls?: MatchUrlDefinitions;
+  propagateTraceHeaderCorsUrls?: MatchUrlDefinitions;
+
+  fetchInstrumentationOptions?: {
+    applyCustomAttributesOnSpan?: FetchCustomAttributeFunction;
+    ignoreNetworkEvents?: boolean;
+  };
+
+  xhrInstrumentationOptions?: {
+    applyCustomAttributesOnSpan?: XHRCustomAttributeFunction;
+    ignoreNetworkEvents?: boolean;
+  };
+};

package/src/utils/sampler.test.ts

@@ -0,0 +1,51 @@
+import { SamplingDecision } from '@opentelemetry/sdk-trace-base';
+
+import { getSamplingDecision } from './sampler';
+
+describe('Sampler', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('Set SamplingDecision to NOT_RECORD (0) if session is not part of the sample', () => {
+    const samplingDecision = getSamplingDecision({
+      attributes: {
+        isSampled: 'false',
+      },
+    });
+
+    expect(samplingDecision).toBe(SamplingDecision.NOT_RECORD);
+  });
+
+  it('Set SamplingDecision to RECORD_AND_SAMPLED (2) if session is part of the sample', () => {
+    const samplingDecision = getSamplingDecision({
+      attributes: {
+        isSampled: 'true',
+      },
+    });
+
+    expect(samplingDecision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it('Set SamplingDecision to NOT_RECORD if session has no attributes', () => {
+    const samplingDecision = getSamplingDecision({});
+
+    expect(samplingDecision).toBe(SamplingDecision.NOT_RECORD);
+  });
+
+  it('Set SamplingDecision to NOT_RECORD if session is undefined', () => {
+    const samplingDecision = getSamplingDecision(undefined);
+
+    expect(samplingDecision).toBe(SamplingDecision.NOT_RECORD);
+  });
+
+  it('Set SamplingDecision to NOT_RECORD if isSampled is missing', () => {
+    const samplingDecision = getSamplingDecision({
+      attributes: {
+        someOtherKey: 'value',
+      },
+    });
+
+    expect(samplingDecision).toBe(SamplingDecision.NOT_RECORD);
+  });
+});

package/src/utils/sampler.ts

@@ -0,0 +1,19 @@
+import { SamplingDecision } from '@opentelemetry/sdk-trace-base';
+
+import type { MetaSession } from '@grafana/faro-core';
+
+/**
+ * Get sampling decision based on session configuration
+ *
+ * If the session is sampled, traces will be collected.
+ * If the session is not sampled, traces will be dropped.
+ *
+ * @param sessionMeta - Current Faro session meta
+ * @returns OTEL sampling decision
+ */
+export function getSamplingDecision(sessionMeta: MetaSession = {}): SamplingDecision {
+  const isSessionSampled = sessionMeta.attributes?.['isSampled'] === 'true';
+  const samplingDecision = isSessionSampled ? SamplingDecision.RECORD_AND_SAMPLED : SamplingDecision.NOT_RECORD;
+
+  return samplingDecision;
+}