@od-oneapp/observability 2026.1.1301

package/src/plugins/sentry-microfrontend/plugin.ts

@@ -0,0 +1,500 @@
+/**
+ * @fileoverview Sentry Micro Frontend Plugin
+ * Sentry Micro Frontend Plugin
+ *
+ * Extends the base Sentry plugin with micro frontend-specific functionality
+ */
+
+import { SentryPlugin } from '@integrations/sentry/observability-plugin/plugin';
+import { logDebug, logError, logWarn } from '@repo/shared/logs';
+
+import {
+  createBackstageBeforeSend,
+  createMultiplexedTransport,
+  enhanceEventWithBackstageApp,
+} from './multiplexed-transport';
+import { mapLogLevelToSentrySeverity } from './sentry-types';
+import {
+  createBackstageScope,
+  detectCurrentBackstageApp,
+  ensureSingleInit,
+  getParentSentry,
+  hasParentSentry,
+  markAsHost,
+} from './utils';
+
+import type { SentryScope, SentrySDK } from './sentry-types';
+import type { MicroFrontendMode, SentryMicroFrontendConfig } from './types';
+import type { LogLevel, ObservabilityContext } from '../../core/types';
+
+/**
+ * Sentry plugin optimized for micro frontend architectures
+ */
+/**
+ * Sentry plugin optimized for micro frontend architectures.
+ *
+ * Extends SentryPlugin with micro frontend-specific features:
+ * - Host/child/standalone mode detection
+ * - Multiplexed transport for routing events to different Sentry projects
+ * - Backstage app context management
+ * - Parent Sentry instance detection and reuse
+ */
+export class SentryMicroFrontendPlugin extends SentryPlugin {
+  private mode: MicroFrontendMode;
+  private backstageApp: string | undefined;
+  private parentSentry: SentrySDK | undefined;
+  private backstageScope: SentryScope | undefined;
+  private microFrontendConfig: SentryMicroFrontendConfig;
+  private eventProcessorCleanup?: (() => void) | undefined;
+
+  /**
+   * Create a new SentryMicroFrontendPlugin instance.
+   *
+   * @param config - Sentry micro frontend plugin configuration
+   */
+  constructor(config: SentryMicroFrontendConfig = {}) {
+    // Determine operation mode
+    const mode = SentryMicroFrontendPlugin.determineMode(config);
+
+    // Prepare base config based on mode
+    const baseConfig = SentryMicroFrontendPlugin.prepareConfig(config, mode);
+
+    // Initialize parent class
+    super(baseConfig);
+
+    this.mode = mode;
+    this.microFrontendConfig = config;
+    this.backstageApp = config.backstageApp ?? detectCurrentBackstageApp(config.backstageApps);
+
+    // Handle parent Sentry if in child mode
+    if (this.mode === 'child') {
+      const parent = getParentSentry();
+      if (parent) {
+        this.parentSentry = parent as SentrySDK;
+        this.enabled = true; // Re-enable since we'll use parent
+
+        // Create backstageApp-specific scope
+        if (this.backstageApp && this.parentSentry.Scope) {
+          this.backstageScope = createBackstageScope(
+            this.backstageApp,
+            config.globalTags,
+          ) as SentryScope;
+        }
+      }
+    }
+
+    // Mark as host if applicable
+    if (this.mode === 'host') {
+      markAsHost(this.backstageApp);
+    }
+  }
+
+  /**
+   * Determine the operation mode based on configuration and environment.
+   *
+   * @param config - Plugin configuration
+   * @returns Operation mode ('host', 'child', or 'standalone')
+   */
+  private static determineMode(config: SentryMicroFrontendConfig): MicroFrontendMode {
+    // Explicit host mode
+    if (config.isHost) {
+      return 'host';
+    }
+
+    // Check for parent Sentry
+    if (config.detectParent !== false && hasParentSentry()) {
+      return 'child';
+    }
+
+    // Default to standalone
+    return 'standalone';
+  }
+
+  /**
+   * Prepare configuration based on operation mode.
+   *
+   * Adjusts configuration settings based on whether running as host, child, or standalone.
+   *
+   * @param config - Original plugin configuration
+   * @param mode - Determined operation mode
+   * @returns Prepared configuration object
+   */
+  private static prepareConfig(
+    config: SentryMicroFrontendConfig,
+    mode: MicroFrontendMode,
+  ): SentryMicroFrontendConfig {
+    const preparedConfig = { ...config };
+
+    if (mode === 'child') {
+      // Disable initialization in child mode
+      preparedConfig.enabled = false;
+    } else if (
+      mode === 'host' &&
+      config.backstageApps &&
+      config.useMultiplexedTransport !== false
+    ) {
+      // Host mode with multiplexed transport is handled in initialize()
+      // Don't set transport here as it needs Sentry to be loaded first
+    }
+
+    return preparedConfig;
+  }
+
+  /**
+   * Initialize the plugin
+   */
+  async initialize(config?: SentryMicroFrontendConfig): Promise<void> {
+    const mergedConfig = { ...this.microFrontendConfig, ...config };
+
+    if (this.mode === 'child') {
+      // In child mode, we don't initialize Sentry but set up our client reference
+      if (this.parentSentry) {
+        this.client = this.parentSentry;
+        this.initialized = true;
+
+        // Configure parent Sentry to include backstageApp information
+        if (this.backstageApp && mergedConfig.addBackstageContext !== false) {
+          this.configureParentSentry();
+        }
+      }
+      return;
+    }
+
+    // For host and standalone modes
+    if (mergedConfig.preventDuplicateInit !== false) {
+      try {
+        ensureSingleInit();
+      } catch (error) {
+        logError('Sentry initialization prevented', { error });
+        this.enabled = false;
+        return;
+      }
+    }
+
+    // Initialize parent class
+    await super.initialize(mergedConfig);
+
+    // Additional setup for host mode
+    if (this.mode === 'host' && this.client && mergedConfig.backstageApps) {
+      this.setupHostMode(mergedConfig);
+    }
+  }
+
+  /**
+   * Configure parent Sentry instance for child mode
+   */
+  private configureParentSentry(): void {
+    if (!this.parentSentry || !this.backstageApp) {
+      logWarn(
+        '[SentryMicroFrontendPlugin] Cannot configure parent Sentry: missing parentSentry or backstageApp',
+      );
+      return;
+    }
+
+    try {
+      // Create event processor
+
+      const processor = (event: any) => {
+        try {
+          if (this.shouldProcessEvent(event)) {
+            enhanceEventWithBackstageApp(event, this.backstageApp ?? '', {
+              mode: this.mode,
+              plugin: 'SentryMicroFrontendPlugin',
+            });
+          }
+        } catch (error) {
+          logError('[SentryMicroFrontendPlugin] Error processing event', { error, event });
+        }
+        return event;
+      };
+
+      // Add global event processor to include backstageApp information
+      if (typeof this.parentSentry.addEventProcessor === 'function') {
+        this.parentSentry.addEventProcessor(processor);
+
+        // Store cleanup function
+        this.eventProcessorCleanup = () => {
+          // Note: Sentry SDK doesn't provide a way to remove event processors
+          // We'll mark events as processed to avoid double processing
+        };
+      } else {
+        logWarn('[SentryMicroFrontendPlugin] Parent Sentry does not support addEventProcessor');
+      }
+    } catch (error) {
+      logError('[SentryMicroFrontendPlugin] Failed to configure parent Sentry', { error });
+    }
+  }
+
+  /**
+   * Set up host mode with multiplexed transport
+   */
+  private setupHostMode(config: SentryMicroFrontendConfig): void {
+    if (!config.backstageApps || !this.client) {
+      logWarn(
+        '[SentryMicroFrontendPlugin] Cannot setup host mode: missing backstageApps or client',
+      );
+      return;
+    }
+
+    try {
+      // Create multiplexed transport
+      const transport = createMultiplexedTransport(
+        config.backstageApps,
+        config.fallbackDsn ?? config.dsn,
+        this.client,
+      );
+
+      if (transport && typeof (this.client as any).init === 'function') {
+        // Re-initialize with multiplexed transport
+        const currentOptions =
+          typeof (this.client as any).getOptions === 'function'
+            ? (this.client as any).getOptions()
+            : {};
+
+        (this.client as any).init({
+          ...currentOptions,
+          transport,
+          beforeSend: createBackstageBeforeSend(this.backstageApp ?? 'main', config.beforeSend),
+        });
+      } else {
+        logWarn(
+          '[SentryMicroFrontendPlugin] Client does not support init method or transport creation failed',
+        );
+      }
+    } catch (error) {
+      logError('[SentryMicroFrontendPlugin] Failed to setup host mode', { error });
+    }
+  }
+
+  /**
+   * Check if we should process this event
+   */
+
+  private shouldProcessEvent(event: any): boolean {
+    // Don't double-process events
+    if (event.tags?.microFrontendProcessed) {
+      return false;
+    }
+
+    // Check if event is from our backstageApp
+    if (
+      this.backstageApp &&
+      event.tags?.backstageApp &&
+      event.tags.backstageApp !== this.backstageApp
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Capture an exception with backstageApp context
+   */
+  captureException(error: Error | unknown, context?: ObservabilityContext): void {
+    if (!this.enabled) return;
+
+    try {
+      if (this.mode === 'child' && this.parentSentry && this.backstageScope) {
+        // Use parent Sentry with backstageApp scope
+        if (typeof this.parentSentry.withScope === 'function') {
+          this.parentSentry.withScope((scope: any) => {
+            try {
+              // Copy backstageApp scope properties
+              if (this.backstageScope && typeof scope.setTag === 'function') {
+                scope.setTag('backstageApp', this.backstageApp ?? 'unknown');
+                scope.setTag('microFrontend', true);
+                scope.setContext('microFrontend', {
+                  backstageApp: this.backstageApp,
+                  mode: this.mode,
+                });
+              }
+
+              // Add additional context
+              if (context && typeof scope.setContext === 'function') {
+                scope.setContext('additional', context);
+              }
+
+              if (this.parentSentry && typeof this.parentSentry.captureException === 'function') {
+                this.parentSentry.captureException(error);
+              }
+            } catch (scopeError) {
+              logError('[SentryMicroFrontendPlugin] Error in scope callback', {
+                error: scopeError,
+              });
+            }
+          });
+        } else {
+          logWarn('[SentryMicroFrontendPlugin] Parent Sentry does not support withScope');
+        }
+      } else {
+        // Use standard capture with backstageApp enhancement
+        const enhancedContext = {
+          ...context,
+          microFrontend: {
+            backstageApp: this.backstageApp,
+            mode: this.mode,
+          },
+        };
+        super.captureException(error, enhancedContext);
+      }
+    } catch (captureError) {
+      logError('[SentryMicroFrontendPlugin] Failed to capture exception', { error: captureError });
+    }
+  }
+
+  /**
+   * Capture a message with backstageApp context
+   */
+  captureMessage(message: string, level: LogLevel = 'info', context?: ObservabilityContext): void {
+    if (!this.enabled) return;
+
+    try {
+      const sentryLevel = mapLogLevelToSentrySeverity(level);
+
+      if (this.mode === 'child' && this.parentSentry && this.backstageScope) {
+        // Use parent Sentry with backstageApp scope
+        if (typeof this.parentSentry.withScope === 'function') {
+          this.parentSentry.withScope((scope: SentryScope) => {
+            try {
+              // Copy backstageApp scope properties
+              if (this.backstageScope && typeof scope.setTag === 'function') {
+                scope.setTag('backstageApp', this.backstageApp ?? 'unknown');
+                scope.setTag('microFrontend', true);
+                if (typeof scope.setContext === 'function') {
+                  scope.setContext('microFrontend', {
+                    backstageApp: this.backstageApp,
+                    mode: this.mode,
+                  });
+                }
+              }
+
+              // Add additional context
+              if (context && typeof scope.setContext === 'function') {
+                scope.setContext('additional', context);
+              }
+
+              if (this.parentSentry && typeof this.parentSentry.captureMessage === 'function') {
+                this.parentSentry.captureMessage(message, sentryLevel);
+              }
+            } catch (scopeError) {
+              logError('[SentryMicroFrontendPlugin] Error in scope callback', {
+                error: scopeError,
+              });
+            }
+          });
+        } else {
+          logWarn('[SentryMicroFrontendPlugin] Parent Sentry does not support withScope');
+        }
+      } else {
+        // Use standard capture
+        super.captureMessage(message, level, context);
+      }
+    } catch (captureError) {
+      logError('[SentryMicroFrontendPlugin] Failed to capture message', { error: captureError });
+    }
+  }
+
+  /**
+   * Get the current operation mode
+   */
+  getMode(): MicroFrontendMode {
+    return this.mode;
+  }
+
+  /**
+   * Get the current Backstage app identifier
+   */
+  getBackstageApp(): string | undefined {
+    return this.backstageApp;
+  }
+
+  /**
+   * @deprecated Use getBackstageApp instead.
+   */
+  getZone(): string | undefined {
+    return this.getBackstageApp();
+  }
+
+  /**
+   * Get debug information about the plugin state
+   */
+
+  getDebugInfo(): Record<string, any> {
+    return {
+      mode: this.mode,
+      backstageApp: this.backstageApp,
+      enabled: this.enabled,
+      initialized: this.initialized,
+      hasParentSentry: this.mode === 'child' && Boolean(this.parentSentry),
+      clientType: this.client ? this.client.constructor.name : 'none',
+    };
+  }
+
+  /**
+   * Clean up the plugin and release resources
+   */
+  async cleanup(): Promise<void> {
+    try {
+      // Clean up event processor if it exists
+      if (this.eventProcessorCleanup) {
+        this.eventProcessorCleanup();
+        this.eventProcessorCleanup = undefined;
+      }
+
+      // Clear backstageApp scope
+
+      if (this.backstageScope && typeof (this.backstageScope as any).clear === 'function') {
+        (this.backstageScope as any).clear();
+      }
+      this.backstageScope = undefined;
+
+      // Clear parent Sentry reference
+      this.parentSentry = undefined;
+
+      // Call parent cleanup
+      await super.cleanup();
+
+      // Mark as not initialized
+      this.initialized = false;
+      this.enabled = false;
+
+      logDebug('[SentryMicroFrontendPlugin] Cleanup completed');
+    } catch (error) {
+      logError('[SentryMicroFrontendPlugin] Error during cleanup', { error });
+    }
+  }
+
+  /**
+   * Destroy the plugin (alias for cleanup)
+   */
+  async destroy(): Promise<void> {
+    await this.cleanup();
+  }
+}
+
+/**
+ * Factory function to create a Sentry Micro Frontend plugin.
+ *
+ * Creates a configured SentryMicroFrontendPlugin instance with micro frontend-specific
+ * features like multiplexed transport and backstage app routing.
+ *
+ * @param config - Optional Sentry micro frontend plugin configuration
+ * @returns SentryMicroFrontendPlugin instance
+ *
+ * @example
+ * ```typescript
+ * const sentry = createSentryMicroFrontendPlugin({
+ *   dsn: 'https://...',
+ *   backstage: [
+ *     { name: 'admin', dsn: 'https://admin-dsn...' },
+ *     { name: 'dashboard', dsn: 'https://dashboard-dsn...' },
+ *   ],
+ * });
+ * ```
+ */
+export const createSentryMicroFrontendPlugin = (
+  config?: SentryMicroFrontendConfig,
+): SentryMicroFrontendPlugin => {
+  return new SentryMicroFrontendPlugin(config);
+};

package/src/plugins/sentry-microfrontend/sentry-types.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Type definitions for Sentry SDK
+ * Type definitions for Sentry SDK
+ * These are minimal types to avoid using 'any' throughout the plugin
+ */
+
+import type { LogLevel } from '../../core/types';
+
+/**
+ * Sentry Scope interface
+ */
+export interface SentryScope {
+  setTag(key: string, value: string | number | boolean | null): void;
+  setContext(key: string, context: Record<string, any> | null): void;
+  setUser(user: Record<string, any> | null): void;
+  setLevel(level: SentrySeverityLevel): void;
+  setFingerprint(fingerprint: string[]): void;
+  clear(): void;
+}
+
+/**
+ * Sentry Hub interface
+ */
+export interface SentryHub {
+  getScope(): SentryScope;
+  pushScope(): SentryScope;
+  popScope(): boolean;
+  withScope(callback: (scope: SentryScope) => void): void;
+}
+
+/**
+ * Sentry Client interface
+ */
+export interface SentryClient {
+  captureException(exception: any, hint?: any): string;
+  captureMessage(message: string, level?: SentrySeverityLevel): string;
+  captureEvent(event: any): string;
+  flush(timeout?: number): Promise<boolean>;
+  close(timeout?: number): Promise<boolean>;
+  getOptions(): SentryOptions;
+  getCurrentHub?(): SentryHub;
+}
+
+/**
+ * Sentry SDK interface
+ */
+export interface SentrySDK {
+  init(options: SentryOptions): void;
+  captureException(exception: any, captureContext?: any): string;
+  captureMessage(message: string, captureContext?: any): string;
+  captureEvent(event: any, hint?: any): string;
+  withScope(callback: (scope: SentryScope) => void): void;
+  addBreadcrumb(breadcrumb: any): void;
+  setUser(user: any): void;
+  setTag(key: string, value: string): void;
+  setContext(key: string, context: any): void;
+  setExtra(key: string, extra: any): void;
+  getCurrentHub(): SentryHub;
+  getClient<T extends SentryClient>(): T | undefined;
+  flush(timeout?: number): Promise<boolean>;
+  close(timeout?: number): Promise<boolean>;
+  lastEventId(): string | undefined;
+
+  // Integration methods
+  addEventProcessor(processor: (event: any) => any | null): void;
+
+  // Browser specific
+  Scope?: new () => SentryScope;
+
+  // Transport creation
+  makeMultiplexedTransport?(
+    createTransport: (options: any) => any,
+    matcher: (options: any) => any[],
+  ): any;
+  makeFetchTransport?(options: any): any;
+
+  // Integrations
+  browserTracingIntegration?(): any;
+  browserProfilingIntegration?(): any;
+  replayIntegration?(options?: any): any;
+  captureConsoleIntegration?(options?: any): any;
+  feedbackIntegration?(options?: any): any;
+  vercelAIIntegration?(): any;
+}
+
+/**
+ * Sentry Options interface
+ */
+export interface SentryOptions {
+  dsn?: string;
+  release?: string;
+  environment?: string;
+  debug?: boolean;
+  sampleRate?: number;
+  tracesSampleRate?: number;
+  profilesSampleRate?: number;
+  replaysSessionSampleRate?: number;
+  replaysOnErrorSampleRate?: number;
+  transport?: any;
+  integrations?: any[];
+  beforeSend?: (event: any, hint: any) => any | null;
+  beforeSendTransaction?: (event: any, hint: any) => any | null;
+  beforeBreadcrumb?: (breadcrumb: any, hint?: any) => any | null;
+  tracePropagationTargets?: (string | RegExp)[];
+  initialScope?: any;
+  maxBreadcrumbs?: number;
+  attachStacktrace?: boolean;
+  autoSessionTracking?: boolean;
+  sendDefaultPii?: boolean;
+
+  _experiments?: Record<string, any>;
+}
+
+/**
+ * Sentry Severity Level
+ */
+export type SentrySeverityLevel = 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug';
+
+/**
+ * Map LogLevel to Sentry Severity.
+ *
+ * Converts the observability package's LogLevel to Sentry's SeverityLevel format.
+ *
+ * @param level - Log level from observability package
+ * @returns Corresponding Sentry severity level
+ */
+export function mapLogLevelToSentrySeverity(level: LogLevel): SentrySeverityLevel {
+  switch (level) {
+    case 'error':
+      return 'error';
+    case 'warning':
+      return 'warning';
+    case 'info':
+      return 'info';
+    case 'debug':
+      return 'debug';
+    default:
+      return 'info';
+  }
+}