@od-oneapp/observability 2026.1.1301

package/src/plugins/sentry/__tests__/plugin-tracing.test.ts

@@ -0,0 +1,511 @@
+/**
+ * @fileoverview Tests for Sentry plugin tracing functionality
+ * Tests for Sentry plugin tracing functionality
+ */
+
+import * as SentryObservabilityPlugin from '@integrations/sentry/observability-plugin';
+import { afterEach, beforeEach, describe, expect, vi } from 'vitest';
+
+const { SentryPlugin } = SentryObservabilityPlugin;
+type SentryPluginConfig = SentryObservabilityPlugin.SentryPluginConfig;
+
+// Mock environment
+vi.mock('@integrations/sentry/observability-plugin', async importOriginal => {
+  const actual = await importOriginal<typeof SentryObservabilityPlugin>();
+  return {
+    ...actual,
+    safeEnv: vi.fn(() => ({
+      SENTRY_DSN: 'https://key@sentry.io/project',
+      SENTRY_ENVIRONMENT: 'test',
+      SENTRY_TRACES_SAMPLE_RATE: 1.0,
+    })),
+  };
+});
+
+// Legacy mock kept for reference (no longer used)
+vi.mock('../env', () => ({
+  safeEnv: vi.fn(() => ({
+    SENTRY_DSN: 'https://key@sentry.io/project',
+    SENTRY_ENVIRONMENT: 'test',
+    SENTRY_TRACES_SAMPLE_RATE: 1.0,
+  })),
+}));
+
+// Helper to inject mock client directly into plugin for testing
+function injectMockClient(
+  pluginInstance: InstanceType<typeof SentryPlugin>,
+  mockClient: any,
+): void {
+  // Access protected properties for testing via type casting
+  const pluginAny = pluginInstance as any;
+  pluginAny.client = mockClient;
+  pluginAny.initialized = true;
+  pluginAny.enabled = true;
+}
+
+describe('sentryPlugin - Tracing', () => {
+  let plugin: InstanceType<typeof SentryPlugin>;
+  let mockSentryClient: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // Mock Sentry client
+    mockSentryClient = {
+      init: vi.fn(),
+      captureException: vi.fn(),
+      captureMessage: vi.fn(),
+      setUser: vi.fn(),
+      addBreadcrumb: vi.fn(),
+      withScope: vi.fn(),
+      getCurrentScope: vi.fn(),
+      getActiveTransaction: vi.fn(),
+      startTransaction: vi.fn(),
+      startSpan: vi.fn(),
+      configureScope: vi.fn(),
+      getCurrentHub: vi.fn(),
+      flush: vi.fn(),
+      close: vi.fn(),
+      browserTracingIntegration: vi.fn(() => ({ name: 'BrowserTracing' })),
+      replayIntegration: vi.fn(() => ({ name: 'Replay' })),
+      profilesIntegration: vi.fn(() => ({ name: 'Profiling' })),
+    };
+
+    const config: SentryPluginConfig = {
+      sentryPackage: '@sentry/nextjs',
+      dsn: 'https://key@sentry.io/project',
+    };
+
+    plugin = new SentryPlugin(config);
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('transaction Management', () => {
+    beforeEach(async () => {
+      // Inject mock client directly instead of relying on dynamic import mocking
+      injectMockClient(plugin, mockSentryClient);
+    });
+
+    it('should start transaction', () => {
+      const mockTransaction = {
+        setMeasurement: vi.fn(),
+        setTag: vi.fn(),
+        finish: vi.fn(),
+        startChild: vi.fn(),
+      };
+
+      mockSentryClient.startTransaction.mockReturnValue(mockTransaction);
+
+      const context = {
+        name: 'test-transaction',
+        op: 'http.server',
+        data: { method: 'GET' },
+      };
+
+      const result = plugin.startTransaction(context);
+
+      expect(result).toBe(mockTransaction);
+      expect(mockSentryClient.startTransaction).toHaveBeenCalledWith(context, undefined);
+    });
+
+    it('should start transaction with custom sampling context', () => {
+      const mockTransaction = { finish: vi.fn() };
+      mockSentryClient.startTransaction.mockReturnValue(mockTransaction);
+
+      const context = { name: 'test', op: 'custom' };
+      const samplingContext = { request: { method: 'POST' } };
+
+      plugin.startTransaction(context, samplingContext);
+
+      expect(mockSentryClient.startTransaction).toHaveBeenCalledWith(context, samplingContext);
+    });
+
+    it('should handle missing startTransaction method', () => {
+      mockSentryClient.startTransaction = undefined;
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const result = plugin.startTransaction({ name: 'test' });
+
+      expect(result).toBeUndefined();
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[node]',
+        'startTransaction not available in this Sentry version',
+      );
+    });
+
+    it('should get active transaction', () => {
+      const mockTransaction = { name: 'active-transaction' };
+      mockSentryClient.getActiveTransaction.mockReturnValue(mockTransaction);
+
+      const result = plugin.getActiveTransaction();
+
+      expect(result).toBe(mockTransaction);
+      expect(mockSentryClient.getActiveTransaction).toHaveBeenCalledWith();
+    });
+
+    it('should get active transaction from scope fallback', () => {
+      const mockTransaction = { name: 'scope-transaction' };
+      const mockScope = { getTransaction: vi.fn(() => mockTransaction) };
+
+      mockSentryClient.getActiveTransaction = undefined;
+      mockSentryClient.getCurrentScope.mockReturnValue(mockScope);
+
+      const result = plugin.getActiveTransaction();
+
+      expect(result).toBe(mockTransaction);
+      expect(mockScope.getTransaction).toHaveBeenCalledWith();
+    });
+  });
+
+  describe('span Management', () => {
+    beforeEach(async () => {
+      injectMockClient(plugin, mockSentryClient);
+    });
+
+    it('should start span', () => {
+      const mockSpan = { finish: vi.fn() };
+      mockSentryClient.startSpan.mockReturnValue(mockSpan);
+
+      const context = {
+        name: 'test-span',
+        op: 'db.query',
+        data: { table: 'users' },
+      };
+
+      const result = plugin.startSpan(context);
+
+      expect(result).toBe(mockSpan);
+      expect(mockSentryClient.startSpan).toHaveBeenCalledWith(context);
+    });
+
+    it('should start span from active transaction fallback', () => {
+      const mockSpan = { finish: vi.fn() };
+      const mockTransaction = { startChild: vi.fn(() => mockSpan) };
+
+      mockSentryClient.startSpan = undefined;
+      mockSentryClient.getActiveTransaction.mockReturnValue(mockTransaction);
+
+      const context = { name: 'child-span' };
+      const result = plugin.startSpan(context);
+
+      expect(result).toBe(mockSpan);
+      expect(mockTransaction.startChild).toHaveBeenCalledWith(context);
+    });
+
+    it('should return undefined when no span creation method available', () => {
+      mockSentryClient.startSpan = undefined;
+      mockSentryClient.getActiveTransaction.mockReturnValue(null);
+
+      const result = plugin.startSpan({ name: 'test' });
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('scope Management', () => {
+    beforeEach(async () => {
+      injectMockClient(plugin, mockSentryClient);
+    });
+
+    it('should configure scope', () => {
+      const callback = vi.fn();
+
+      plugin.configureScope(callback);
+
+      expect(mockSentryClient.configureScope).toHaveBeenCalledWith(callback);
+    });
+
+    it('should use withScope fallback', () => {
+      const callback = vi.fn();
+      mockSentryClient.configureScope = undefined;
+
+      plugin.configureScope(callback);
+
+      expect(mockSentryClient.withScope).toHaveBeenCalledWith(callback);
+    });
+
+    it('should get current hub', () => {
+      const mockHub = { getScope: vi.fn() };
+      mockSentryClient.getCurrentHub.mockReturnValue(mockHub);
+
+      const result = plugin.getCurrentHub();
+
+      expect(result).toBe(mockHub);
+      expect(mockSentryClient.getCurrentHub).toHaveBeenCalledWith();
+    });
+  });
+
+  describe('performance Measurements', () => {
+    let mockTransaction: any;
+
+    beforeEach(async () => {
+      injectMockClient(plugin, mockSentryClient);
+      mockTransaction = {
+        setMeasurement: vi.fn(),
+        setTag: vi.fn(),
+        setData: vi.fn(),
+        traceId: 'trace-123',
+        spanId: 'span-456',
+      };
+      mockSentryClient.getActiveTransaction.mockReturnValue(mockTransaction);
+    });
+
+    it('should set measurement on active transaction', () => {
+      plugin.setMeasurement('response_time', 150, 'millisecond');
+
+      expect(mockTransaction.setMeasurement).toHaveBeenCalledWith(
+        'response_time',
+        150,
+        'millisecond',
+      );
+    });
+
+    it('should handle no active transaction', () => {
+      mockSentryClient.getActiveTransaction.mockReturnValue(null);
+
+      plugin.setMeasurement('response_time', 150);
+
+      expect(mockTransaction.setMeasurement).not.toHaveBeenCalled();
+    });
+
+    it('should record web vital', () => {
+      plugin.recordWebVital('LCP', 2500, {
+        unit: 'millisecond',
+        rating: 'good',
+      });
+
+      expect(mockTransaction.setMeasurement).toHaveBeenCalledWith('lcp', 2500, 'millisecond');
+      expect(mockTransaction.setTag).toHaveBeenCalledWith('webvital.lcp.rating', 'good');
+      expect(mockSentryClient.captureMessage).toHaveBeenCalledWith('Web Vital: LCP', {
+        level: 'info',
+        tags: {
+          'webvital.name': 'LCP',
+          'webvital.value': 2500,
+          'webvital.unit': 'millisecond',
+          'webvital.rating': 'good',
+        },
+        contexts: {
+          trace: {
+            trace_id: 'trace-123',
+            span_id: 'span-456',
+          },
+        },
+      });
+    });
+
+    it('should add performance entries', () => {
+      const entries: PerformanceEntry[] = [
+        {
+          name: 'navigation',
+          entryType: 'navigation',
+          startTime: 0,
+          duration: 1500,
+        } as PerformanceNavigationTiming,
+        {
+          name: 'https://example.com/script.js',
+          entryType: 'resource',
+          startTime: 100,
+          duration: 200,
+        } as PerformanceResourceTiming,
+      ];
+
+      plugin.addPerformanceEntries(
+        entries as unknown as Array<{
+          entryType: string;
+          name: string;
+          startTime: number;
+          duration: number;
+          [key: string]: unknown;
+        }>,
+      );
+
+      expect(mockSentryClient.addBreadcrumb).toHaveBeenCalledTimes(2);
+
+      // Check navigation entry breadcrumb
+      expect(mockSentryClient.addBreadcrumb).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          category: 'performance',
+          message: 'navigation: navigation',
+          data: expect.objectContaining({
+            name: 'navigation',
+            duration: 1500,
+            startTime: 0,
+          }),
+        }),
+      );
+
+      // Check resource entry breadcrumb
+      expect(mockSentryClient.addBreadcrumb).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          category: 'performance',
+          message: 'resource: https://example.com/script.js',
+          data: expect.objectContaining({
+            name: 'https://example.com/script.js',
+            duration: 200,
+            startTime: 100,
+          }),
+        }),
+      );
+    });
+  });
+
+  describe('performance API Integration', () => {
+    beforeEach(async () => {
+      injectMockClient(plugin, mockSentryClient);
+    });
+
+    it('should create performance mark', () => {
+      const mockPerformance = {
+        mark: vi.fn(),
+      };
+      Object.defineProperty(global, 'performance', {
+        value: mockPerformance,
+        configurable: true,
+      });
+
+      plugin.mark('test-mark', { detail: { step: 1 } });
+
+      expect(mockPerformance.mark).toHaveBeenCalledWith('test-mark', {
+        detail: { step: 1 },
+      });
+      expect(mockSentryClient.addBreadcrumb).toHaveBeenCalledWith({
+        category: 'performance.mark',
+        message: 'test-mark',
+        data: { step: 1 },
+        timestamp: expect.any(Number),
+      });
+    });
+
+    it('should create performance measure', () => {
+      const mockMeasure = {
+        name: 'test-measure',
+        duration: 150,
+        startTime: 1000,
+      };
+
+      const mockPerformance = {
+        measure: vi.fn(),
+        getEntriesByName: vi.fn(() => [mockMeasure]),
+      };
+
+      Object.defineProperty(global, 'performance', {
+        value: mockPerformance,
+        configurable: true,
+      });
+
+      const mockTransaction = {
+        setMeasurement: vi.fn(),
+      };
+      mockSentryClient.getActiveTransaction.mockReturnValue(mockTransaction);
+
+      plugin.measure('test-measure', 'start-mark', 'end-mark');
+
+      expect(mockPerformance.measure).toHaveBeenCalledWith(
+        'test-measure',
+        'start-mark',
+        'end-mark',
+      );
+      expect(mockTransaction.setMeasurement).toHaveBeenCalledWith(
+        'test-measure',
+        150,
+        'millisecond',
+      );
+      expect(mockSentryClient.addBreadcrumb).toHaveBeenCalledWith({
+        category: 'performance.measure',
+        message: 'test-measure',
+        data: {
+          duration: 150,
+          startTime: 1000,
+        },
+        timestamp: 1,
+      });
+    });
+
+    it('should handle performance measure with options', () => {
+      const mockMeasure = {
+        name: 'test-measure',
+        duration: 100,
+        startTime: 2000,
+      };
+
+      const mockPerformance = {
+        measure: vi.fn(),
+        getEntriesByName: vi.fn(() => [mockMeasure]),
+      };
+
+      Object.defineProperty(global, 'performance', {
+        value: mockPerformance,
+        configurable: true,
+      });
+
+      const options = { start: '1000', end: '1100' };
+      plugin.measure('test-measure', options);
+
+      expect(mockPerformance.measure).toHaveBeenCalledWith('test-measure', options);
+    });
+  });
+
+  describe('plugin State Management', () => {
+    it('should not perform tracing operations when disabled', () => {
+      plugin.enabled = false;
+
+      const result = plugin.startTransaction({ name: 'test' });
+      expect(result).toBeUndefined();
+
+      const span = plugin.startSpan({ name: 'test' });
+      expect(span).toBeUndefined();
+
+      plugin.setMeasurement('test', 100);
+      plugin.recordWebVital('LCP', 2500);
+      plugin.mark('test-mark');
+      plugin.measure('test-measure');
+
+      expect(mockSentryClient.startTransaction).not.toHaveBeenCalled();
+      expect(mockSentryClient.startSpan).not.toHaveBeenCalled();
+    });
+
+    it('should not perform operations when client is not available', async () => {
+      plugin = new SentryPlugin({ dsn: 'invalid-dsn' });
+      // Don't initialize to keep client undefined
+
+      const result = plugin.startTransaction({ name: 'test' });
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('flush and Cleanup', () => {
+    beforeEach(async () => {
+      injectMockClient(plugin, mockSentryClient);
+    });
+
+    it('should flush client', async () => {
+      mockSentryClient.flush.mockResolvedValue(true);
+
+      const result = await plugin.flush(5000);
+
+      expect(result).toBeTruthy();
+      expect(mockSentryClient.flush).toHaveBeenCalledWith(5000);
+    });
+
+    it('should handle flush errors', async () => {
+      mockSentryClient.flush.mockRejectedValue(new Error('Flush failed'));
+
+      const result = await plugin.flush();
+
+      expect(result).toBeFalsy();
+    });
+
+    it('should return true when flush is not available', async () => {
+      mockSentryClient.flush = undefined;
+
+      const result = await plugin.flush();
+
+      expect(result).toBeTruthy();
+    });
+  });
+});

package/src/plugins/sentry/env.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Sentry-specific environment configuration
+ * Sentry-specific environment configuration
+ * Apps can extend this configuration to inherit Sentry environment variables
+ */
+
+import { logWarn } from '@repo/shared/logger';
+import { createEnv } from '@t3-oss/env-core';
+import { z } from 'zod/v4';
+
+// Create validated env object
+export const env = createEnv({
+  server: {
+    SENTRY_DSN: z.string().url().optional(),
+    SENTRY_AUTH_TOKEN: z.string().optional(),
+    SENTRY_ORG: z.string().optional(),
+    SENTRY_PROJECT: z.string().optional(),
+    SENTRY_ENVIRONMENT: z.enum(['development', 'preview', 'production']).optional(),
+    SENTRY_RELEASE: z.string().optional(),
+    SENTRY_TRACES_SAMPLE_RATE: z.coerce.number().min(0).max(1).optional(),
+    SENTRY_PROFILES_SAMPLE_RATE: z.coerce.number().min(0).max(1).optional(),
+    SENTRY_REPLAYS_SESSION_SAMPLE_RATE: z.coerce.number().min(0).max(1).optional(),
+    SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE: z.coerce.number().min(0).max(1).optional(),
+    SENTRY_DEBUG: z
+      .string()
+      .optional()
+      .transform(val => val === 'true')
+      .default(false),
+  },
+  clientPrefix: 'NEXT_PUBLIC_',
+  client: {
+    NEXT_PUBLIC_SENTRY_DSN: z.string().url().optional(),
+    NEXT_PUBLIC_SENTRY_ENVIRONMENT: z.enum(['development', 'preview', 'production']).optional(),
+    NEXT_PUBLIC_SENTRY_RELEASE: z.string().optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+  onInvalidAccess: (variable: string) => {
+    throw new Error(
+      `❌ Attempted to access a server-side environment variable on the client: ${variable}`,
+    );
+  },
+  onValidationError: error => {
+    // Note: Using logWarn during env validation - shared logger is always available
+    logWarn('Sentry environment validation failed', { error });
+    // Don't throw in packages - use fallbacks
+    return undefined as never;
+  },
+});
+
+/**
+ * Safe environment access for non-Next.js contexts.
+ *
+ * Provides fallback environment variable access for Node.js, workers, and test environments
+ * where the validated env object may not be available. Returns fallback values with proper
+ * type coercion and defaults.
+ *
+ * @returns Environment object with Sentry configuration values
+ */
+export function safeEnv() {
+  if (env) return env;
+
+  // Fallback values for resilience
+  return {
+    // Server
+    SENTRY_DSN: process.env.SENTRY_DSN ?? '',
+    SENTRY_AUTH_TOKEN: process.env.SENTRY_AUTH_TOKEN ?? '',
+    SENTRY_ORG: process.env.SENTRY_ORG ?? '',
+    SENTRY_PROJECT: process.env.SENTRY_PROJECT ?? '',
+    SENTRY_ENVIRONMENT:
+      (process.env.SENTRY_ENVIRONMENT as 'development' | 'preview' | 'production') ?? 'development',
+    SENTRY_RELEASE: process.env.SENTRY_RELEASE ?? '',
+    SENTRY_TRACES_SAMPLE_RATE:
+      Number(process.env.SENTRY_TRACES_SAMPLE_RATE) ||
+      (process.env.NODE_ENV === 'production' ? 0.1 : 1.0),
+    SENTRY_PROFILES_SAMPLE_RATE: Number(process.env.SENTRY_PROFILES_SAMPLE_RATE) ?? 0,
+    SENTRY_REPLAYS_SESSION_SAMPLE_RATE:
+      Number(process.env.SENTRY_REPLAYS_SESSION_SAMPLE_RATE) ||
+      (process.env.NODE_ENV === 'production' ? 0.1 : 0),
+    SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE:
+      Number(process.env.SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE) || 1.0,
+    SENTRY_DEBUG: process.env.SENTRY_DEBUG === 'true',
+    // Client
+    NEXT_PUBLIC_SENTRY_DSN: process.env.NEXT_PUBLIC_SENTRY_DSN ?? '',
+    NEXT_PUBLIC_SENTRY_ENVIRONMENT:
+      (process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT as 'development' | 'preview' | 'production') ??
+      'development',
+    NEXT_PUBLIC_SENTRY_RELEASE: process.env.NEXT_PUBLIC_SENTRY_RELEASE ?? '',
+  };
+}
+
+// Export type
+export type Env = typeof env;

package/src/plugins/sentry/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Sentry plugin exports
+ * Sentry plugin exports
+ * Provides full access to @sentry/nextjs while wrapping in plugin interface
+ */
+
+// Re-export everything from @sentry/nextjs for full Next.js access
+export * from '@sentry/nextjs';
+
+// Export plugin and factory
+export { SentryPlugin, createSentryPlugin, defaultBeforeSendLog } from './plugin';
+export type { SentryPluginConfig } from './plugin';
+
+// Re-export Sentry environment configuration
+export { env, safeEnv } from './env';
+export type { Env } from './env';
+
+// Export types
+export type { ObservabilityPlugin, ObservabilityServerPlugin } from '../../core/plugin';
+export type {
+  Hub,
+  Scope,
+  Span,
+  SpanContext,
+  SpanStatus,
+  Transaction,
+  TransactionContext,
+} from './types';