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

package/src/instrumentations/http/instrumentation.test.ts

@@ -0,0 +1,373 @@
+import { type EventEvent, initializeFaro, type TransportItem } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { HttpInstrumentation } from './index';
+
+const FARO_TRACING_FETCH_EVENT = 'faro.tracing.fetch';
+
+describe('HttpInstrumentation', () => {
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  describe('initialization', () => {
+    it('should patch global fetch', () => {
+      const transport = new MockTransport();
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      expect(global.fetch).not.toBe(originalFetch);
+    });
+
+    it('should have correct name and version', () => {
+      const instrumentation = new HttpInstrumentation();
+      expect(instrumentation.name).toBe('@grafana/faro-react-native:instrumentation-http');
+      expect(typeof instrumentation.version).toBe('string');
+    });
+  });
+
+  describe('fetch tracking', () => {
+    it('should track successful fetch requests with faro.tracing.fetch event', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200, statusText: 'OK' });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://api.example.com/data');
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.url']).toBe('https://api.example.com/data');
+      expect(fetchEvent?.payload.attributes?.['http.method']).toBe('GET');
+      expect(fetchEvent?.payload.attributes?.['http.status_code']).toBe('200');
+      expect(fetchEvent?.payload.attributes?.['http.scheme']).toBe('https');
+      expect(fetchEvent?.payload.attributes?.['http.host']).toBe('api.example.com');
+      expect(fetchEvent?.payload.attributes?.['duration_ns']).toBeDefined();
+    });
+
+    it('should track POST requests', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 201 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://api.example.com/data', { method: 'POST' });
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.method']).toBe('POST');
+      expect(fetchEvent?.payload.attributes?.['http.url']).toBe('https://api.example.com/data');
+    });
+
+    it('should track failed fetch requests with faro.tracing.fetch event', async () => {
+      const transport = new MockTransport();
+      const error = new Error('Network error');
+      global.fetch = jest.fn().mockRejectedValue(error);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://api.example.com/data').catch(() => {});
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.status_code']).toBe('0');
+      expect(fetchEvent?.payload.attributes?.['http.error']).toBe('Network error');
+      expect(fetchEvent?.payload.attributes?.['duration_ns']).toBeDefined();
+      // HTTP failures are tracked as events only (no pushError); Grafana FEO derives HTTP Errors from events
+    });
+
+    it('should handle URL object input', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      const url = new URL('https://api.example.com/data');
+      await fetch(url);
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.url']).toBe('https://api.example.com/data');
+    });
+
+    it('should handle Request object input', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      const request = new Request('https://api.example.com/data', { method: 'POST' });
+      await fetch(request);
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.url']).toBe('https://api.example.com/data');
+      expect(fetchEvent?.payload.attributes?.['http.method']).toBe('POST');
+    });
+  });
+
+  describe('URL filtering', () => {
+    it('should ignore Grafana collector URLs', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://faro.grafana.net/collect');
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvents = events.filter((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvents).toHaveLength(0);
+    });
+
+    it('should ignore URLs matching custom patterns', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [
+            new HttpInstrumentation({
+              ignoredUrls: [/localhost/, /127\.0\.0\.1/, /internal-api/],
+            }),
+          ],
+        })
+      );
+
+      await fetch('http://localhost:3000/api');
+      await fetch('http://127.0.0.1:8080/data');
+      await fetch('https://api.example.com/internal-api/users');
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvents = events.filter((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvents).toHaveLength(0);
+    });
+
+    it('should track non-ignored URLs', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [
+            new HttpInstrumentation({
+              ignoredUrls: [/localhost/],
+            }),
+          ],
+        })
+      );
+
+      await fetch('https://api.example.com/data');
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvents = events.filter((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvents.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('request timing', () => {
+    it('should calculate request duration', async () => {
+      jest.useFakeTimers();
+
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      let resolvePromise: (value: Response) => void;
+      const fetchPromise = new Promise<Response>((resolve) => {
+        resolvePromise = resolve;
+      });
+      global.fetch = jest.fn().mockReturnValue(fetchPromise);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      const request = fetch('https://api.example.com/data');
+
+      jest.advanceTimersByTime(500);
+
+      resolvePromise!(mockResponse);
+      await request;
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent?.payload.attributes?.['duration_ns']).toBeDefined();
+      expect(typeof fetchEvent?.payload.attributes?.['duration_ns']).toBe('string');
+
+      jest.useRealTimers();
+    });
+
+    it('should track request_size and response_size when available', async () => {
+      const transport = new MockTransport();
+      const requestBody = JSON.stringify({ key: 'value' });
+      const mockResponse = new Response('{"ok":true}', {
+        status: 200,
+        headers: { 'Content-Length': '14' },
+      });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://api.example.com/data', {
+        method: 'POST',
+        body: requestBody,
+      });
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvent = events.find((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvent).toBeDefined();
+      expect(fetchEvent?.payload.attributes?.['http.request_size']).toBe(String(requestBody.length));
+      expect(fetchEvent?.payload.attributes?.['http.response_size']).toBe('14');
+    });
+  });
+
+  describe('unpatch', () => {
+    it('should restore original fetch', () => {
+      const mockFetch = jest.fn();
+      global.fetch = mockFetch;
+
+      const { config } = initializeFaro(
+        mockConfig({
+          transports: [new MockTransport()],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      const patchedFetch = global.fetch;
+      expect(patchedFetch).not.toBe(mockFetch);
+
+      const instrumentation = config.instrumentations?.[0] as HttpInstrumentation;
+      instrumentation.unpatch();
+
+      expect(global.fetch).toBe(mockFetch);
+    });
+
+    it('should clear tracked requests', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      const mockFetch = jest.fn().mockResolvedValue(mockResponse);
+
+      const savedFetch = global.fetch;
+      global.fetch = mockFetch;
+
+      const { config } = initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await fetch('https://api.example.com/data1');
+      await fetch('https://api.example.com/data2');
+
+      const instrumentation = config.instrumentations?.[0] as HttpInstrumentation;
+      instrumentation.unpatch();
+
+      expect(() => instrumentation.unpatch()).not.toThrow();
+
+      global.fetch = savedFetch;
+    });
+  });
+
+  describe('concurrent requests', () => {
+    it('should track multiple concurrent requests', async () => {
+      const transport = new MockTransport();
+      const mockResponse = new Response('{}', { status: 200 });
+      global.fetch = jest.fn().mockResolvedValue(mockResponse);
+
+      initializeFaro(
+        mockConfig({
+          transports: [transport],
+          instrumentations: [new HttpInstrumentation()],
+        })
+      );
+
+      await Promise.all([
+        fetch('https://api.example.com/data1'),
+        fetch('https://api.example.com/data2'),
+        fetch('https://api.example.com/data3'),
+      ]);
+
+      const events = transport.items.filter((item) => item.type === 'event') as TransportItem<EventEvent>[];
+      const fetchEvents = events.filter((e) => e.payload.name === FARO_TRACING_FETCH_EVENT);
+
+      expect(fetchEvents).toHaveLength(3);
+
+      const urls = fetchEvents.map((e) => e.payload.attributes?.['http.url']).sort();
+      expect(urls).toContain('https://api.example.com/data1');
+      expect(urls).toContain('https://api.example.com/data2');
+      expect(urls).toContain('https://api.example.com/data3');
+    });
+  });
+});

package/src/instrumentations/http/utils.ts

@@ -0,0 +1,58 @@
+export interface HttpRequestPayload {
+  url: string;
+  method: string;
+  requestId: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  status?: number;
+  error?: string;
+  requestSize?: number;
+  responseSize?: number;
+}
+
+/**
+ * Parse URL for scheme and host. Returns empty strings if parsing fails.
+ */
+export function parseUrlParts(url: string): { scheme: string; host: string } {
+  try {
+    const parsed = new URL(url);
+    return {
+      scheme: parsed.protocol.replace(':', '') || 'http',
+      host: parsed.host || '',
+    };
+  } catch {
+    return { scheme: 'http', host: '' };
+  }
+}
+
+/**
+ * Build Web SDK-style event attributes for faro.tracing.fetch.
+ * Aligns with Grafana HTTP insights and Frontend Observability plugin.
+ */
+export function buildFetchEventAttributes(payload: HttpRequestPayload): Record<string, string> {
+  const { scheme, host } = parseUrlParts(payload.url);
+  const durationNs = payload.duration != null ? String(Math.round(payload.duration * 1_000_000)) : '';
+  const statusCode = payload.status != null ? String(payload.status) : '0';
+
+  const attrs: Record<string, string> = {
+    'http.url': payload.url,
+    'http.method': payload.method,
+    'http.scheme': scheme,
+    'http.host': host,
+    'http.status_code': statusCode,
+    duration_ns: durationNs,
+  };
+
+  if (payload.requestSize != null) {
+    attrs['http.request_size'] = String(payload.requestSize);
+  }
+  if (payload.responseSize != null) {
+    attrs['http.response_size'] = String(payload.responseSize);
+  }
+  if (payload.error) {
+    attrs['http.error'] = payload.error;
+  }
+
+  return attrs;
+}

package/src/instrumentations/performance/index.ts

@@ -0,0 +1,172 @@
+import { NativeModules } from 'react-native';
+
+import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
+
+import type { PerformanceInstrumentationOptions } from './types';
+
+const { FaroReactNativeModule } = NativeModules;
+
+/**
+ * Measures React Native app performance metrics (CPU and Memory usage)
+ *
+ * Collects periodic performance metrics using native OS APIs:
+ * - iOS: task_info() for memory, host_statistics() for CPU
+ * - Android: /proc/[pid]/status for memory, /proc/[pid]/stat for CPU
+ *
+ * Implementation ported from Faro Flutter SDK with feature parity.
+ *
+ * **Key Features**:
+ * - ✅ NO manual setup required - OS tracks metrics automatically!
+ * - ✅ Periodic collection (default: every 30 seconds)
+ * - ✅ Configurable per-metric enable/disable
+ * - ✅ Differential CPU calculation (accurate usage percentages)
+ * - ✅ Memory usage in KB (Resident Set Size)
+ *
+ * **Metrics Captured**:
+ * - `mem_usage`: Current memory usage in KB (RSS - physical memory)
+ * - `cpu_usage`: Current CPU usage percentage (0-100+)
+ *
+ * **Requirements**:
+ * - iOS 13.4+ (any iOS that supports React Native)
+ * - Android API 21+ for CPU (Android 5.0 Lollipop, ~99% of devices)
+ * - Android any version for Memory
+ *
+ * @example
+ * ```tsx
+ * import { initializeFaro, getRNInstrumentations } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   url: 'https://your-collector.com',
+ *   instrumentations: [
+ *     ...getRNInstrumentations({
+ *       memoryUsageVitals: true,      // default: true
+ *       cpuUsageVitals: true,          // default: true
+ *       fetchVitalsInterval: 30000,    // default: 30s
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class PerformanceInstrumentation extends BaseInstrumentation {
+  readonly name = '@grafana/faro-react-native:instrumentation-performance';
+  readonly version = VERSION;
+
+  private options: Required<PerformanceInstrumentationOptions>;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: PerformanceInstrumentationOptions = {}) {
+    super();
+    this.options = {
+      memoryUsageVitals: options.memoryUsageVitals ?? true,
+      cpuUsageVitals: options.cpuUsageVitals ?? true,
+      fetchVitalsInterval: options.fetchVitalsInterval ?? 30000,
+    };
+  }
+
+  initialize(): void {
+    // Only start if at least one metric is enabled
+    if (!this.options.memoryUsageVitals && !this.options.cpuUsageVitals) {
+      this.logInfo('Performance monitoring disabled - no metrics enabled');
+      return;
+    }
+
+    // Check native module availability
+    if (!FaroReactNativeModule) {
+      this.logWarn(
+        'Native module not available. Performance instrumentation requires native module. ' +
+          'Run `cd ios && pod install` and rebuild the app.'
+      );
+      return;
+    }
+
+    // Start periodic collection
+    this.startPeriodicCollection();
+  }
+
+  private startPeriodicCollection(): void {
+    // Collect immediately on initialization
+    this.collectMetrics();
+
+    // Then collect periodically
+    this.intervalId = setInterval(() => {
+      this.collectMetrics();
+    }, this.options.fetchVitalsInterval);
+
+    this.logInfo(
+      `Performance monitoring started - collecting every ${this.options.fetchVitalsInterval}ms ` +
+        `(memory: ${this.options.memoryUsageVitals}, cpu: ${this.options.cpuUsageVitals})`
+    );
+  }
+
+  private collectMetrics(): void {
+    // Collect memory if enabled
+    if (this.options.memoryUsageVitals) {
+      this.collectMemoryUsage();
+    }
+
+    // Collect CPU if enabled
+    if (this.options.cpuUsageVitals) {
+      this.collectCpuUsage();
+    }
+  }
+
+  private collectMemoryUsage(): void {
+    try {
+      if (!FaroReactNativeModule?.getMemoryUsage) {
+        this.logDebug('Memory: getMemoryUsage not available on native module');
+        return;
+      }
+
+      const memoryUsage = FaroReactNativeModule.getMemoryUsage();
+      if (memoryUsage == null || memoryUsage <= 0) {
+        this.logDebug('Memory: skipping - value is null or <= 0');
+        return;
+      }
+
+      this.logDebug(`Memory: pushing measurement with mem_usage = ${memoryUsage}`);
+      this.api.pushMeasurement({
+        type: 'app_memory',
+        values: { mem_usage: memoryUsage },
+      });
+    } catch (error) {
+      this.logError('Failed to collect memory usage', error);
+    }
+  }
+
+  private collectCpuUsage(): void {
+    try {
+      if (!FaroReactNativeModule?.getCpuUsage) {
+        this.logDebug('CPU: getCpuUsage not available on native module');
+        return;
+      }
+
+      const cpuUsage = FaroReactNativeModule.getCpuUsage();
+      this.logDebug(`CPU: raw value = ${cpuUsage}`);
+
+      // Validate CPU usage (Flutter SDK filters 0-100 range, but allows >100)
+      // Skip null, negative, or exactly 0 (baseline reading)
+      if (cpuUsage == null || cpuUsage <= 0) {
+        this.logDebug('CPU: skipping - value is null or <= 0');
+        return;
+      }
+
+      this.logDebug(`CPU: pushing measurement with cpu_usage = ${cpuUsage}`);
+      // Flutter SDK also filters values >= 100, but we allow them as they can be valid
+      // in multi-core scenarios where one core is maxed out
+      this.api.pushMeasurement({
+        type: 'app_cpu_usage',
+        values: { cpu_usage: cpuUsage },
+      });
+    } catch (error) {
+      this.logError('Failed to collect CPU usage', error);
+    }
+  }
+
+  unpatch(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+      this.logInfo('Performance monitoring stopped');
+    }
+  }
+}