@od-oneapp/observability 2026.1.1301

package/src/plugins/sentry/plugin.ts

@@ -0,0 +1,953 @@
+/**
+ * @fileoverview Sentry plugin implementation
+ * Sentry plugin implementation
+ */
+
+import { logDebug, logError, logWarn } from '@repo/shared/logger';
+import type { ObservabilityServerPlugin } from '../../core/plugin';
+import type {
+  Breadcrumb,
+  LogLevel,
+  ObservabilityContext,
+  ObservabilityUser,
+} from '../../core/types';
+import { isBrowser } from '../../shared';
+import { safeEnv } from './env';
+import type { Hub, Scope, Span, SpanContext, Transaction, TransactionContext } from './types';
+
+/**
+ * Default log filter function that filters out noisy development logs.
+ * Filters out:
+ * - Next.js Fast Refresh messages
+ * - HMR (Hot Module Replacement) messages
+ * - Prisma query logs (server-only)
+ * - Prisma engine/info logs
+ * - SQL queries matching Prisma's format
+ *
+ * Handles ANSI color codes, console formatting (%c, %s), and CSS styling.
+ *
+ * @param log - The log entry from Sentry
+ * @param isServer - Whether this is running on the server (defaults to true)
+ * @returns The log entry if it should be sent, or null to filter it out
+ */
+export function defaultBeforeSendLog(log: any, isServer = true): any | null {
+  // Check both message and any formatted message fields
+  const messageToCheck = log.message || log.formatted || '';
+  if (!messageToCheck) {
+    return log; // No message to filter, send as-is
+  }
+
+  const message = String(messageToCheck);
+
+  // Remove ANSI color codes for comparison (e.g., \u001b[34mprisma:query\u001b[39m)
+  // Also handle %c format codes used by console styling and %s placeholders
+  const messageWithoutAnsi = message
+    .replace(/\u001b\[[0-9;]*m/g, '') // Remove ANSI escape codes
+    .replace(/%[csdfiO]/g, '') // Remove console format placeholders (%c, %s, %d, %f, %i, %o)
+    .replace(/background:[^;]+;?/g, '') // Remove CSS background styles
+    .replace(/color:[^;]+;?/g, '') // Remove CSS color styles
+    .replace(/border-radius:[^;]+;?/g, '') // Remove CSS border-radius
+    .replace(/light-dark\([^)]+\)/g, '') // Remove light-dark() CSS functions
+    .replace(/rgba?\([^)]+\)/g, '') // Remove rgba/rgb color functions
+    .replace(/#[0-9a-fA-F]{3,8}/g, '') // Remove hex colors
+    .toLowerCase(); // Case-insensitive matching
+
+  // Filter out Next.js Fast Refresh and HMR messages (both client and server)
+  if (messageWithoutAnsi.includes('[fast refresh]') || messageWithoutAnsi.includes('[hmr]')) {
+    return null; // Drop the log
+  }
+
+  // Filter out Prisma logs (server-only)
+  if (isServer) {
+    if (
+      messageWithoutAnsi.includes('prisma:query') ||
+      messageWithoutAnsi.includes('prisma:engine') ||
+      messageWithoutAnsi.includes('prisma:info') ||
+      // Also filter SQL queries that look like Prisma queries (SELECT ... FROM "public".)
+      (messageWithoutAnsi.includes('select') &&
+        messageWithoutAnsi.includes('from') &&
+        (messageWithoutAnsi.includes('"public".') || messageWithoutAnsi.includes('public.')))
+    ) {
+      return null; // Drop the log
+    }
+  }
+
+  return log; // Send the log
+}
+
+/**
+ * Minimal Sentry interface for common methods across all Sentry packages
+ */
+interface SentryClient {
+  init(options: any): void;
+  captureException(error: any, captureContext?: any): string;
+  captureMessage(message: string, captureContext?: any): string;
+  setUser(user: any): void;
+  addBreadcrumb(breadcrumb: any): void;
+  withScope(callback: (scope: any) => void): void;
+  getCurrentScope?(): any;
+  getActiveTransaction?(): any;
+  startTransaction?(context: TransactionContext, customSamplingContext?: any): any;
+  startSpan?(context: SpanContext): any;
+  configureScope?(callback: (scope: any) => void): void;
+  getCurrentHub?(): any;
+  flush?(timeout?: number): Promise<boolean>;
+  close?(timeout?: number): Promise<boolean>;
+  browserTracingIntegration?(): any;
+  replayIntegration?(): any;
+  profilesIntegration?(): any;
+  consoleLoggingIntegration?(options?: { levels?: string[] }): any;
+  logger?: {
+    trace(message: string, attributes?: Record<string, unknown>): void;
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    error(message: string, attributes?: Record<string, unknown>): void;
+    fatal(message: string, attributes?: Record<string, unknown>): void;
+    fmt(strings: TemplateStringsArray, ...values: unknown[]): string;
+  };
+}
+
+/**
+ * Sentry plugin configuration
+ */
+export interface SentryPluginConfig {
+  /**
+   * The Sentry package to use (e.g., '@sentry/node', '@sentry/browser', '@sentry/nextjs')
+   * If not provided, the plugin will try to detect based on environment
+   */
+  sentryPackage?: string;
+
+  // Core Sentry options
+  dsn?: string;
+  environment?: string;
+  release?: string;
+  enabled?: boolean;
+  debug?: boolean;
+
+  // Sampling rates
+  tracesSampleRate?: number;
+  profilesSampleRate?: number;
+  replaysSessionSampleRate?: number;
+  replaysOnErrorSampleRate?: number;
+
+  // Integrations and hooks
+  integrations?: any[];
+  beforeSend?: (event: any, hint: any) => any;
+  beforeSendTransaction?: (event: any, hint: any) => any;
+  beforeBreadcrumb?: (breadcrumb: any, hint?: any) => any;
+  beforeSendLog?: (log: any) => any;
+
+  // Logging options
+  enableLogs?: boolean;
+  consoleLoggingIntegration?: {
+    levels?: ('log' | 'warn' | 'error' | 'debug' | 'info' | 'assert' | 'trace')[];
+  };
+
+  // Trace propagation
+  tracePropagationTargets?: (string | RegExp)[];
+
+  // Other options
+  initialScope?: any;
+  maxBreadcrumbs?: number;
+  attachStacktrace?: boolean;
+  autoSessionTracking?: boolean;
+  sendDefaultPii?: boolean;
+}
+
+/**
+ * Sentry plugin implementation
+ */
+/**
+ * Sentry plugin implementation.
+ *
+ * Integrates Sentry error tracking and performance monitoring into the observability system.
+ * Auto-detects the appropriate Sentry package (@sentry/node, @sentry/browser, @sentry/nextjs)
+ * based on the runtime environment.
+ */
+export class SentryPlugin<
+  T extends SentryClient = SentryClient,
+> implements ObservabilityServerPlugin<T> {
+  name = 'sentry';
+  enabled: boolean;
+  protected client: T | undefined;
+  protected initialized = false;
+  protected sentryPackage: string;
+  protected config: SentryPluginConfig;
+
+  /**
+   * Create a new SentryPlugin instance.
+   *
+   * @param config - Sentry plugin configuration
+   */
+  constructor(config: SentryPluginConfig = {}) {
+    this.config = config;
+    const env = safeEnv();
+    // Auto-enable if DSN is provided
+    const hasDSN = config.dsn ?? env.SENTRY_DSN ?? env.NEXT_PUBLIC_SENTRY_DSN;
+    this.enabled = config.enabled ?? Boolean(hasDSN);
+
+    // Determine Sentry package to use
+    this.sentryPackage = config.sentryPackage ?? this.detectSentryPackage();
+  }
+
+  /**
+   * Detect which Sentry package to use based on the runtime environment.
+   *
+   * @returns Package name ('@sentry/node', '@sentry/browser', or '@sentry/nextjs')
+   */
+  private detectSentryPackage(): string {
+    if (isBrowser()) {
+      return '@sentry/browser';
+    } else if (process.env.NEXT_RUNTIME === 'edge') {
+      return '@sentry/nextjs'; // Next.js edge uses same package
+    } else if (process.env.NEXT_RUNTIME) {
+      return '@sentry/nextjs';
+    } else {
+      return '@sentry/node';
+    }
+  }
+
+  getClient(): T | undefined {
+    return this.client;
+  }
+
+  /**
+   * Get safe environment access (for testing/mocking).
+   *
+   * @returns Environment configuration object
+   */
+  protected getSafeEnv() {
+    return safeEnv();
+  }
+
+  async initialize(config?: SentryPluginConfig): Promise<void> {
+    if (this.initialized || !this.enabled) return;
+
+    const env = safeEnv();
+    const mergedConfig = { ...this.config, ...config };
+
+    // Check for DSN
+    const dsn = mergedConfig.dsn ?? env.SENTRY_DSN ?? env.NEXT_PUBLIC_SENTRY_DSN;
+    if (!dsn) {
+      logWarn('Sentry plugin: No DSN provided, skipping initialization');
+      this.enabled = false;
+      return;
+    }
+
+    try {
+      // Dynamic import of the specified Sentry package
+      this.client = (await import(/* webpackIgnore: true */ this.sentryPackage)) as T;
+
+      if (this.client && this.enabled) {
+        // Build integrations array if not provided
+        let { integrations } = mergedConfig;
+        if (!integrations && this.client.browserTracingIntegration) {
+          integrations = [];
+
+          // Add browser tracing for performance monitoring
+          if (
+            mergedConfig.tracesSampleRate !== undefined ||
+            env.SENTRY_TRACES_SAMPLE_RATE !== undefined
+          ) {
+            integrations.push(this.client.browserTracingIntegration());
+          }
+
+          // Add replay integration if configured
+          if (
+            this.client.replayIntegration &&
+            (mergedConfig.replaysSessionSampleRate !== undefined ||
+              env.SENTRY_REPLAYS_SESSION_SAMPLE_RATE !== undefined)
+          ) {
+            integrations.push(this.client.replayIntegration());
+          }
+
+          // Add profiling if configured
+          if (
+            this.client.profilesIntegration &&
+            (mergedConfig.profilesSampleRate !== undefined ||
+              env.SENTRY_PROFILES_SAMPLE_RATE !== undefined)
+          ) {
+            integrations.push(this.client.profilesIntegration());
+          }
+        }
+
+        // Add console logging integration if logs are enabled
+        const enableLogs = mergedConfig.enableLogs ?? true;
+        if (enableLogs && this.client.consoleLoggingIntegration) {
+          const consoleLoggingConfig = mergedConfig.consoleLoggingIntegration || {
+            levels: ['log', 'warn', 'error'],
+          };
+          if (!integrations) {
+            integrations = [];
+          }
+          integrations.push(this.client.consoleLoggingIntegration(consoleLoggingConfig));
+        }
+
+        this.client.init({
+          dsn,
+          environment: mergedConfig.environment ?? env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV,
+          release: mergedConfig.release ?? env.SENTRY_RELEASE,
+          debug: mergedConfig.debug ?? env.SENTRY_DEBUG,
+
+          // Enable logs to be sent to Sentry
+          enableLogs,
+
+          // Sampling rates
+          tracesSampleRate: mergedConfig.tracesSampleRate ?? env.SENTRY_TRACES_SAMPLE_RATE,
+          profilesSampleRate: mergedConfig.profilesSampleRate ?? env.SENTRY_PROFILES_SAMPLE_RATE,
+          replaysSessionSampleRate:
+            mergedConfig.replaysSessionSampleRate ?? env.SENTRY_REPLAYS_SESSION_SAMPLE_RATE,
+          replaysOnErrorSampleRate:
+            mergedConfig.replaysOnErrorSampleRate ?? env.SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE,
+
+          // Integrations and hooks
+          integrations,
+          beforeSend: mergedConfig.beforeSend,
+          beforeSendTransaction: mergedConfig.beforeSendTransaction,
+          // Use provided beforeSendLog, or default filter if logs are enabled and no custom filter provided
+          beforeSendLog:
+            mergedConfig.beforeSendLog ||
+            (enableLogs ? (log: any) => defaultBeforeSendLog(log, !isBrowser()) : undefined),
+
+          // Other options
+          tracePropagationTargets: mergedConfig.tracePropagationTargets,
+          initialScope: mergedConfig.initialScope,
+          maxBreadcrumbs: mergedConfig.maxBreadcrumbs,
+          attachStacktrace: mergedConfig.attachStacktrace,
+          autoSessionTracking: mergedConfig.autoSessionTracking,
+        });
+
+        this.initialized = true;
+      }
+    } catch (error) {
+      logError(`Failed to import Sentry package '${this.sentryPackage}'`, { error });
+      this.enabled = false;
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.client && this.initialized) {
+      // Use close if available, otherwise flush
+      if (this.client.close) {
+        await this.client.close();
+      } else if (this.client.flush) {
+        await this.client.flush();
+      }
+      this.initialized = false;
+    }
+  }
+
+  /**
+   * Clean up the plugin (alias for shutdown)
+   */
+  async cleanup(): Promise<void> {
+    await this.shutdown();
+  }
+
+  captureException(error: Error | unknown, context?: ObservabilityContext): void {
+    if (!this.enabled || !this.client) return;
+
+    // Additional build-time guard to prevent errors during static generation
+    if (typeof this.client.captureException !== 'function') {
+      // During build/static generation, Sentry client may not be properly initialized
+      // Fall back to logging in development
+      if (process.env.NODE_ENV === 'development') {
+        logError('[Sentry Fallback] Exception', { error });
+      }
+      return;
+    }
+
+    try {
+      this.client.captureException(error, context);
+    } catch (captureError) {
+      // Graceful fallback if Sentry fails during build
+      if (process.env.NODE_ENV === 'development') {
+        logWarn('[Sentry Plugin] Failed to capture exception', { error: captureError });
+        logError('[Sentry Fallback] Exception', { error });
+      }
+    }
+  }
+
+  captureMessage(message: string, level: LogLevel = 'info', context?: ObservabilityContext): void {
+    if (!this.enabled || !this.client) return;
+
+    // Prefer Sentry.logger if available (structured logs)
+    if (this.client.logger) {
+      try {
+        const attributes: Record<string, unknown> | undefined = context
+          ? ((context.extra as Record<string, unknown> | undefined) ??
+            (context as Record<string, unknown>))
+          : undefined;
+        switch (level) {
+          case 'debug':
+            this.client.logger.debug(message, attributes);
+            return;
+          case 'info':
+            this.client.logger.info(message, attributes);
+            return;
+          case 'warning':
+            this.client.logger.warn(message, attributes);
+            return;
+          case 'error':
+            this.client.logger.error(message, attributes);
+            return;
+        }
+      } catch (error) {
+        // Fall through to captureMessage if logger fails
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log via logger', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage for compatibility
+    // Additional build-time guard to prevent errors during static generation
+    if (typeof this.client.captureMessage !== 'function') {
+      // During build/static generation, Sentry client may not be properly initialized
+      // Fall back to logging in development
+      if (process.env.NODE_ENV === 'development') {
+        if (level === 'error') {
+          logError(`[Sentry Fallback] ${message}`);
+        } else if (level === 'warning') {
+          logWarn(`[Sentry Fallback] ${message}`);
+        } else {
+          logDebug(`[Sentry Fallback] ${message}`);
+        }
+      }
+      return;
+    }
+
+    // Map our log levels to Sentry severity levels
+    const sentryLevel =
+      level === 'warning'
+        ? 'warning'
+        : level === 'error'
+          ? 'error'
+          : level === 'debug'
+            ? 'debug'
+            : 'info';
+
+    try {
+      // Build capture context from ObservabilityContext
+      const captureContext = context
+        ? {
+            level: sentryLevel,
+            extra: context.extra ?? context,
+            tags: context.tags,
+          }
+        : sentryLevel;
+
+      this.client.captureMessage(message, captureContext);
+    } catch (error) {
+      // Graceful fallback if Sentry fails during build
+      if (process.env.NODE_ENV === 'development') {
+        logWarn('[Sentry Plugin] Failed to capture message', { error });
+        if (level === 'error') {
+          logError(`[Sentry Fallback] ${message}`);
+        } else if (level === 'warning') {
+          logWarn(`[Sentry Fallback] ${message}`);
+        } else {
+          logDebug(`[Sentry Fallback] ${message}`);
+        }
+      }
+    }
+  }
+
+  setUser(user: ObservabilityUser | null): void {
+    if (!this.enabled || !this.client) return;
+    this.client.setUser(user);
+  }
+
+  addBreadcrumb(breadcrumb: Breadcrumb): void {
+    if (!this.enabled || !this.client) return;
+    this.client.addBreadcrumb({
+      ...breadcrumb,
+      timestamp: breadcrumb.timestamp ?? Date.now() / 1000,
+    });
+  }
+
+  withScope(callback: (scope: any) => void): void {
+    if (!this.enabled || !this.client) return;
+    this.client.withScope(callback);
+  }
+
+  /**
+   * Start a new transaction
+   */
+  startTransaction(
+    context: TransactionContext,
+    customSamplingContext?: any,
+  ): Transaction | undefined {
+    if (!this.enabled || !this.client) return undefined;
+
+    if (this.client.startTransaction) {
+      return this.client.startTransaction(context, customSamplingContext);
+    }
+
+    // Fallback for older versions
+    logWarn('startTransaction not available in this Sentry version');
+    return undefined;
+  }
+
+  /**
+   * Start a new span
+   */
+  startSpan(context: SpanContext): Span | undefined {
+    if (!this.enabled || !this.client) return undefined;
+
+    if (this.client.startSpan) {
+      return this.client.startSpan(context);
+    }
+
+    // Try to create span from active transaction
+    const transaction = this.getActiveTransaction();
+    if (transaction?.startChild) {
+      return transaction.startChild(context);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get the currently active transaction
+   */
+  getActiveTransaction(): Transaction | undefined {
+    if (!this.enabled || !this.client) return undefined;
+
+    if (this.client.getActiveTransaction) {
+      return this.client.getActiveTransaction();
+    }
+
+    // Try to get from current scope
+    if (this.client.getCurrentScope) {
+      const scope = this.client.getCurrentScope();
+      if (scope?.getTransaction) {
+        return scope.getTransaction();
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Configure the current scope
+   */
+  configureScope(callback: (scope: Scope) => void): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.configureScope) {
+      this.client.configureScope(callback);
+    } else if (this.client.withScope) {
+      // Fallback using withScope
+      this.client.withScope(callback);
+    }
+  }
+
+  /**
+   * Get the current hub instance
+   */
+  getCurrentHub(): Hub | undefined {
+    if (!this.enabled || !this.client) return undefined;
+
+    if (this.client.getCurrentHub) {
+      return this.client.getCurrentHub();
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Set a measurement on the active transaction
+   */
+  setMeasurement(name: string, value: number, unit?: string): void {
+    if (!this.enabled || !this.client) return;
+
+    const transaction = this.getActiveTransaction();
+    if (transaction?.setMeasurement) {
+      transaction.setMeasurement(name, value, unit);
+    }
+  }
+
+  /**
+   * Add performance entries as breadcrumbs and measurements
+   */
+  addPerformanceEntries(
+    entries: Array<{
+      entryType: string;
+      name: string;
+      startTime: number;
+      duration: number;
+      [key: string]: unknown;
+    }>,
+  ): void {
+    if (!this.enabled || !this.client) return;
+
+    const transaction = this.getActiveTransaction();
+
+    entries.forEach(entry => {
+      // Add as breadcrumb for context
+      this.addBreadcrumb({
+        category: 'performance',
+        message: `${entry.entryType}: ${entry.name}`,
+        data: {
+          name: entry.name,
+          duration: entry.duration,
+          startTime: entry.startTime,
+          ...(entry.entryType === 'navigation' && {
+            transferSize: (entry as { transferSize?: number }).transferSize,
+            encodedBodySize: (entry as { encodedBodySize?: number }).encodedBodySize,
+            decodedBodySize: (entry as { decodedBodySize?: number }).decodedBodySize,
+          }),
+          ...(entry.entryType === 'resource' && {
+            initiatorType: (entry as { initiatorType?: string }).initiatorType,
+            transferSize: (entry as { transferSize?: number }).transferSize,
+          }),
+        },
+      });
+
+      // Add measurements for key metrics
+      if (transaction && entry.entryType === 'navigation') {
+        const navEntry = entry as unknown as {
+          responseStart?: number;
+          fetchStart?: number;
+          domInteractive?: number;
+          domComplete?: number;
+          loadEventEnd?: number;
+          transferSize?: number;
+          encodedBodySize?: number;
+          decodedBodySize?: number;
+          [key: string]: unknown;
+        };
+
+        // Core Web Vitals and other metrics
+        const fetchStart = navEntry.fetchStart ?? 0;
+        if (navEntry.responseStart !== undefined) {
+          this.setMeasurement('fcp', navEntry.responseStart - fetchStart, 'millisecond');
+        }
+        if (navEntry.domInteractive !== undefined) {
+          this.setMeasurement(
+            'dom_interactive',
+            navEntry.domInteractive - fetchStart,
+            'millisecond',
+          );
+        }
+        if (navEntry.domComplete !== undefined) {
+          this.setMeasurement('dom_complete', navEntry.domComplete - fetchStart, 'millisecond');
+        }
+        if (navEntry.loadEventEnd !== undefined) {
+          this.setMeasurement('load_event_end', navEntry.loadEventEnd - fetchStart, 'millisecond');
+        }
+      }
+    });
+  }
+
+  /**
+   * Record a Web Vital measurement
+   */
+  recordWebVital(
+    name: 'FCP' | 'LCP' | 'FID' | 'CLS' | 'TTFB' | 'INP' | string,
+    value: number,
+    options?: {
+      unit?: string;
+      rating?: 'good' | 'needs-improvement' | 'poor';
+    },
+  ): void {
+    if (!this.enabled || !this.client) return;
+
+    const { unit = 'millisecond', rating } = options ?? {};
+    const transaction = this.getActiveTransaction();
+
+    if (transaction) {
+      // Set the measurement
+      transaction.setMeasurement(name.toLowerCase(), value, unit);
+
+      // Add rating as tag if provided
+      if (rating) {
+        transaction.setTag(`webvital.${name.toLowerCase()}.rating`, rating);
+      }
+
+      // Also send as a standalone event for monitoring
+      this.client.captureMessage(`Web Vital: ${name}`, {
+        level: 'info',
+        tags: {
+          'webvital.name': name,
+          'webvital.value': value,
+          'webvital.unit': unit,
+          ...(rating && { 'webvital.rating': rating }),
+        },
+        contexts: {
+          trace: {
+            trace_id: transaction.traceId,
+            span_id: transaction.spanId,
+          },
+        },
+      });
+    }
+  }
+
+  /**
+   * Create a custom performance mark
+   */
+  mark(name: string, options?: { detail?: any }): void {
+    if (!this.enabled) return;
+
+    // Use Performance API if available
+    if (typeof performance !== 'undefined' && performance.mark) {
+      performance.mark(name, options);
+    }
+
+    // Also add as breadcrumb
+    this.addBreadcrumb({
+      category: 'performance.mark',
+      message: name,
+      data: options?.detail,
+      timestamp: Date.now() / 1000,
+    });
+  }
+
+  /**
+   * Create a custom performance measure
+   */
+  measure(
+    name: string,
+    startMarkOrOptions?:
+      | string
+      | { start?: string; end?: string; duration?: number; detail?: unknown },
+    endMark?: string,
+  ): void {
+    if (!this.enabled) return;
+
+    // Use Performance API if available
+    if (typeof performance !== 'undefined' && performance.measure) {
+      if (typeof startMarkOrOptions === 'string') {
+        performance.measure(name, startMarkOrOptions, endMark);
+      } else if (startMarkOrOptions) {
+        performance.measure(name, startMarkOrOptions);
+      } else {
+        // No options provided, create a simple measure
+        performance.measure(name);
+      }
+
+      // Get the measure to record its duration
+      const measures = performance.getEntriesByName(name, 'measure');
+      const measure = measures[measures.length - 1];
+
+      if (measure) {
+        this.setMeasurement(name, measure.duration, 'millisecond');
+
+        this.addBreadcrumb({
+          category: 'performance.measure',
+          message: name,
+          data: {
+            duration: measure.duration,
+            startTime: measure.startTime,
+          },
+          timestamp: measure.startTime / 1000,
+        });
+      }
+    }
+  }
+
+  /**
+   * Log a trace message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Trace message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logTrace(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.trace) {
+      try {
+        this.client.logger.trace(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log trace', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage
+    this.captureMessage(message, 'debug', attributes);
+  }
+
+  /**
+   * Log a debug message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Debug message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logDebug(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.debug) {
+      try {
+        this.client.logger.debug(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log debug', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage
+    this.captureMessage(message, 'debug', attributes);
+  }
+
+  /**
+   * Log an info message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Info message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logInfo(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.info) {
+      try {
+        this.client.logger.info(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log info', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage
+    this.captureMessage(message, 'info', attributes);
+  }
+
+  /**
+   * Log a warning message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Warning message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logWarn(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.warn) {
+      try {
+        this.client.logger.warn(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log warn', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage
+    this.captureMessage(message, 'warning', attributes);
+  }
+
+  /**
+   * Log an error message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Error message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logError(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.error) {
+      try {
+        this.client.logger.error(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log error', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage
+    this.captureMessage(message, 'error', attributes);
+  }
+
+  /**
+   * Log a fatal message using Sentry.logger (if available).
+   * Falls back to captureMessage if logger is not available.
+   *
+   * @param message - Fatal message to log
+   * @param attributes - Optional attributes to include with the log
+   */
+  logFatal(message: string, attributes?: Record<string, unknown>): void {
+    if (!this.enabled || !this.client) return;
+
+    if (this.client.logger?.fatal) {
+      try {
+        this.client.logger.fatal(message, attributes);
+        return;
+      } catch (error) {
+        if (process.env.NODE_ENV === 'development') {
+          logWarn('[Sentry Plugin] Failed to log fatal', { error });
+        }
+      }
+    }
+
+    // Fallback to captureMessage with error level
+    this.captureMessage(message, 'error', attributes);
+  }
+
+  /**
+   * Get the Sentry.logger instance if available.
+   * This allows direct access to Sentry.logger APIs including fmt.
+   *
+   * @returns Sentry.logger instance or undefined if not available
+   *
+   * @example
+   * ```typescript
+   * const logger = sentryPlugin.getLogger();
+   * if (logger) {
+   *   logger.info(logger.fmt`User ${user.id} logged in`);
+   * }
+   * ```
+   */
+  getLogger(): SentryClient['logger'] | undefined {
+    if (!this.enabled || !this.client) return undefined;
+    return this.client.logger;
+  }
+
+  async flush(timeout?: number): Promise<boolean> {
+    if (!this.enabled || !this.client || !this.client.flush) return true;
+    try {
+      return await this.client.flush(timeout);
+    } catch (_error) {
+      return false;
+    }
+  }
+}
+
+/**
+ * Factory function to create a Sentry plugin.
+ *
+ * Creates a configured SentryPlugin instance with optional configuration.
+ * Auto-detects the appropriate Sentry package based on the environment.
+ *
+ * @param config - Optional Sentry plugin configuration
+ * @returns SentryPlugin instance
+ *
+ * @example
+ * ```typescript
+ * const sentry = createSentryPlugin({
+ *   dsn: 'https://...',
+ *   environment: 'production',
+ *   tracesSampleRate: 0.1,
+ * });
+ * ```
+ */
+export const createSentryPlugin = <T extends SentryClient = SentryClient>(
+  config?: SentryPluginConfig,
+): SentryPlugin<T> => {
+  return new SentryPlugin<T>(config);
+};