@od-oneapp/observability 2026.1.1301

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

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Types for Sentry Micro Frontend Plugin
+ * Types for Sentry Micro Frontend Plugin
+ */
+
+import type { SentryPluginConfig } from '../sentry';
+
+/**
+ * Configuration for a specific micro frontend backstageApp
+ */
+export interface BackstageAppConfig {
+  /**
+   * Name of the backstageApp (e.g., 'cms', 'workflows', 'authmgmt')
+   */
+  name: string;
+
+  /**
+   * Sentry DSN for this backstageApp (optional, uses default if not provided)
+   */
+  dsn?: string;
+
+  /**
+   * Release version for this backstageApp
+   */
+  release?: string;
+
+  /**
+   * Additional tags to apply to events from this backstageApp
+   */
+  tags?: Record<string, string>;
+
+  /**
+   * Path patterns that identify this backstageApp
+   */
+  pathPatterns?: (string | RegExp)[];
+}
+
+/**
+ * Mode of operation for the micro frontend
+ */
+export type MicroFrontendMode = 'host' | 'child' | 'standalone';
+
+/**
+ * Configuration for Sentry Micro Frontend Plugin
+ */
+export interface SentryMicroFrontendConfig extends Omit<SentryPluginConfig, 'transport'> {
+  /**
+   * Whether this is the host application that manages routing
+   */
+  isHost?: boolean;
+
+  /**
+   * The backstageApp identifier for this micro frontend (e.g., 'cms', 'workflows')
+   */
+  backstageApp?: string;
+
+  /**
+   * Configuration for all backstage (only used in host mode)
+   */
+  backstageApps?: BackstageAppConfig[];
+
+  /**
+   * Whether to detect and use parent Sentry instance
+   * @default true
+   */
+  detectParent?: boolean;
+
+  /**
+   * Custom function to detect the current backstageApp
+   */
+  backstageAppDetector?: () => string | undefined;
+
+  /**
+   * Whether to add backstageApp information to all events
+   * @default true
+   */
+  addBackstageContext?: boolean;
+
+  /**
+   * Fallback DSN to use if backstageApp-specific DSN is not found
+   */
+  fallbackDsn?: string;
+
+  /**
+   * Whether to use multiplexed transport in host mode
+   * @default true
+   */
+  useMultiplexedTransport?: boolean;
+
+  /**
+   * Global tags to apply to all events
+   */
+  globalTags?: Record<string, string>;
+
+  /**
+   * Whether to prevent initialization if parent exists
+   * @default true
+   */
+  preventDuplicateInit?: boolean;
+
+  /**
+   * Integration configuration to be handled during initialization
+   */
+  integrationConfig?: {
+    nodeProfilingIntegration?: boolean;
+    captureConsoleIntegration?: boolean;
+    vercelAIIntegration?: boolean;
+  };
+
+  /**
+   * Sentry experimental features
+   */
+
+  _experiments?: {
+    enableLogs?: boolean;
+  };
+}
+
+/**
+ * Extended window interface for Sentry
+ */
+declare global {
+  interface Window {
+    Sentry?: any;
+
+    __SENTRY_MICRO_FRONTEND_HOST__?: boolean;
+
+    __SENTRY_MICRO_FRONTEND_APP__?: string;
+  }
+}

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

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview Utility functions for Sentry Micro Frontend Plugin
+ * Utility functions for Sentry Micro Frontend Plugin
+ */
+
+import { logError } from '@repo/shared/logs';
+
+import type { BackstageAppConfig } from './types';
+
+/**
+ * Detect the current micro frontend backstageApp based on URL path.
+ *
+ * Analyzes the current URL pathname to determine which micro frontend application
+ * is active. Supports custom path patterns and falls back to default patterns.
+ *
+ * @param customPatterns - Optional array of custom backstage app configurations with path patterns
+ * @returns Detected backstage app name, or undefined if not detected
+ *
+ * @example
+ * ```typescript
+ * const app = detectCurrentBackstageApp([
+ *   { name: 'admin', pathPatterns: ['/admin', '/manage'] },
+ *   { name: 'dashboard', pathPatterns: [/^\/dashboard/] }
+ * ]);
+ * // Returns: 'admin' if pathname starts with '/admin' or '/manage'
+ * ```
+ */
+export function detectCurrentBackstageApp(
+  customPatterns?: BackstageAppConfig[],
+): string | undefined {
+  // Edge runtime compatible check
+  if (
+    typeof globalThis === 'undefined' ||
+    !(globalThis as { location?: { pathname?: string; href?: string } }).location
+  ) {
+    // Server-side or edge: check Next.js basePath or environment variables
+    // Note: process.env is not available in edge runtime
+    if (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_BASE_PATH) {
+      return process.env.NEXT_PUBLIC_BASE_PATH.replace('/', '');
+    }
+    return undefined;
+  }
+
+  const path = (globalThis as { location?: { pathname?: string } }).location?.pathname;
+  if (!path) {
+    return undefined;
+  }
+
+  // Check custom patterns first
+  if (customPatterns) {
+    for (const config of customPatterns) {
+      if (config.pathPatterns) {
+        for (const pattern of config.pathPatterns) {
+          if (typeof pattern === 'string' && path.startsWith(pattern)) {
+            return config.name;
+          } else if (pattern instanceof RegExp && pattern.test(path)) {
+            return config.name;
+          }
+        }
+      }
+    }
+  }
+
+  // Default patterns for common microfrontend zones
+  if (path.startsWith('/admin')) return 'admin';
+  if (path.startsWith('/dashboard')) return 'dashboard';
+  if (path.startsWith('/settings')) return 'settings';
+
+  // Check for backstageApp in global object (set by host)
+
+  if ((globalThis as any).__SENTRY_MICRO_FRONTEND_APP__) {
+    return (globalThis as any).__SENTRY_MICRO_FRONTEND_APP__;
+  }
+
+  if ((globalThis as any).__SENTRY_MICRO_FRONTEND_ZONE__) {
+    // Backwards compatibility with legacy zone naming
+
+    return (globalThis as any).__SENTRY_MICRO_FRONTEND_ZONE__;
+  }
+
+  return 'main';
+}
+
+/**
+ * Check if running in a host environment.
+ *
+ * Determines whether the current application is acting as a host for micro frontends
+ * or as a child micro frontend. Checks for explicit host markers and Sentry initialization state.
+ *
+ * @returns True if running as host, false if child or standalone
+ */
+export function isHostEnvironment(): boolean {
+  if (typeof globalThis === 'undefined') {
+    return false;
+  }
+
+  // Check if explicitly marked as host
+
+  if ((globalThis as any).__SENTRY_MICRO_FRONTEND_HOST__) {
+    return true;
+  }
+
+  // Check if Sentry is already initialized (likely means we're a child)
+  if (
+    (globalThis as any).Sentry &&
+    typeof (globalThis as any).Sentry.getCurrentHub === 'function'
+  ) {
+    return false;
+  }
+
+  // Default to false (safer to assume child mode)
+  return false;
+}
+
+/**
+ * Create a Sentry scope with backstageApp-specific context.
+ *
+ * Creates a new Sentry scope configured with micro frontend tags and context.
+ * Includes backstageApp tag, microFrontend context, and any additional tags provided.
+ *
+ * @param backstageApp - Name of the backstage app
+ * @param additionalTags - Optional additional tags to set on the scope
+ * @returns Sentry scope instance, or null if Sentry is not available
+ */
+
+export function createBackstageScope(
+  backstageApp: string,
+  additionalTags?: Record<string, string>,
+): unknown {
+  if (typeof globalThis === 'undefined' || !(globalThis as any).Sentry) {
+    return null;
+  }
+
+  const { Sentry } = globalThis as any;
+
+  // Check if Scope constructor is available
+  if (!Sentry.Scope || typeof Sentry.Scope !== 'function') {
+    return null;
+  }
+
+  try {
+    const scope = new Sentry.Scope();
+
+    // Set backstageApp tag
+    scope.setTag('backstageApp', backstageApp);
+    scope.setTag('microFrontend', true);
+
+    // Set backstageApp context
+    scope.setContext('microFrontend', {
+      backstageApp,
+
+      isHost: (globalThis as any).__SENTRY_MICRO_FRONTEND_HOST__ ?? false,
+      url: (globalThis as { location?: { href?: string } }).location?.href ?? undefined,
+    });
+
+    // Add additional tags if provided
+    if (additionalTags) {
+      Object.entries(additionalTags).forEach(([key, value]) => {
+        scope.setTag(key, value);
+      });
+    }
+
+    return scope;
+  } catch (error) {
+    logError('[SentryMicroFrontendPlugin] Failed to create Backstage scope', { error });
+    return null;
+  }
+}
+
+/**
+ * Check if Sentry is already initialized by a parent application.
+ *
+ * Verifies whether a parent Sentry instance exists in the global scope.
+ * Used to determine if the current micro frontend should use the parent's Sentry
+ * or initialize its own instance.
+ *
+ * @returns True if parent Sentry is available, false otherwise
+ */
+export function hasParentSentry(): boolean {
+  if (typeof globalThis === 'undefined') {
+    return false;
+  }
+
+  // Check for Sentry global
+
+  const { Sentry } = globalThis as any;
+  if (!Sentry) {
+    return false;
+  }
+
+  // Verify it's a real Sentry instance with expected methods
+  const requiredMethods = ['captureException', 'captureMessage', 'withScope'];
+  return requiredMethods.every(method => typeof Sentry[method] === 'function');
+}
+
+/**
+ * Get the parent Sentry instance if available.
+ *
+ * Returns the global Sentry instance if it exists and has been initialized
+ * by a parent application. Returns null if no parent Sentry is available.
+ *
+ * @returns Parent Sentry SDK instance, or null if not available
+ */
+
+export function getParentSentry(): any {
+  if (hasParentSentry()) {
+    return (globalThis as any).Sentry;
+  }
+  return null;
+}
+
+/**
+ * Mark the current environment as a host.
+ *
+ * Sets global flags indicating that this application is acting as a host
+ * for micro frontends. This affects how Sentry events are routed and tagged.
+ *
+ * @param backstageApp - Optional backstage app name to set
+ */
+export function markAsHost(backstageApp?: string): void {
+  if (typeof globalThis !== 'undefined') {
+    (globalThis as any).__SENTRY_MICRO_FRONTEND_HOST__ = true;
+    if (backstageApp) {
+      (globalThis as any).__SENTRY_MICRO_FRONTEND_APP__ = backstageApp;
+
+      (globalThis as any).__SENTRY_MICRO_FRONTEND_ZONE__ = backstageApp;
+    }
+  }
+}
+
+/**
+ * Get backstageApp-specific configuration.
+ *
+ * Finds the configuration for a specific backstage app from the provided array.
+ *
+ * @param backstageApp - Name of the backstage app to find
+ * @param backstage - Array of backstage app configurations
+ * @returns Configuration for the specified app, or undefined if not found
+ */
+export function getBackstageAppConfig(
+  backstageApp: string,
+  backstage: BackstageAppConfig[],
+): BackstageAppConfig | undefined {
+  return backstage.find(app => app.name === backstageApp);
+}
+
+/**
+ * Ensure only one Sentry initialization happens (thread-safe).
+ *
+ * Prevents multiple Sentry initializations using global state tracking.
+ * Uses timestamps and unique IDs to detect concurrent initialization attempts.
+ * Throws an error if Sentry is already initialized or if concurrent initialization is detected.
+ *
+ * @throws Error if Sentry is already initialized or concurrent initialization detected
+ */
+export function ensureSingleInit(): void {
+  // Use a more robust initialization check with timestamps
+  const initKey = '__SENTRY_INIT_STATE__';
+  const now = Date.now();
+
+  if (typeof globalThis !== 'undefined') {
+    const globalState = (globalThis as any)[initKey];
+
+    // Check if already initialized or currently initializing
+    if (globalState) {
+      const { status, timestamp, id } = globalState;
+
+      // If initialized, throw error
+      if (status === 'initialized') {
+        throw new Error(
+          'Sentry has already been initialized! Use hasParentSentry() to check before initializing.',
+        );
+      }
+
+      // If initializing and it's been less than 5 seconds, assume another process is initializing
+      if (status === 'initializing' && now - timestamp < 5000) {
+        throw new Error(
+          `Sentry initialization already in progress (started ${now - timestamp}ms ago by ${id})`,
+        );
+      }
+    }
+
+    // Mark as initializing with timestamp and unique ID
+    const initId = `${now}-${Math.random().toString(36).substr(2, 9)}`;
+
+    (globalThis as any)[initKey] = {
+      status: 'initializing',
+      timestamp: now,
+      id: initId,
+    };
+
+    // Small delay to allow for race condition detection
+    // In a real thread-safe implementation, this would use proper locking
+
+    const checkState = (globalThis as any)[initKey];
+    if (checkState.id !== initId) {
+      throw new Error('Concurrent Sentry initialization detected');
+    }
+
+    // Mark as initialized
+
+    (globalThis as any)[initKey] = {
+      status: 'initialized',
+      timestamp: now,
+      id: initId,
+    };
+
+    // Also set legacy flag for backward compatibility
+
+    (globalThis as any).__SENTRY_INITIALIZED__ = true;
+  }
+}
+
+/**
+ * Reset initialization flag (mainly for testing).
+ *
+ * Clears the global Sentry initialization state. Useful for testing scenarios
+ * where you need to test initialization multiple times.
+ */
+export function resetInitFlag(): void {
+  if (typeof globalThis !== 'undefined') {
+    delete (globalThis as any).__SENTRY_INITIALIZED__;
+
+    delete (globalThis as any).__SENTRY_INIT_STATE__;
+  }
+}

package/src/server-edge.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Next.js edge runtime observability export
+ * Next.js edge runtime observability export
+ * Limited to fetch-based implementations only
+ */
+
+import { env } from '../env';
+
+import { ObservabilityBuilder } from './factory/builder';
+import { createBetterStackPlugin } from './plugins/betterstack';
+import { env as betterStackEnv } from './plugins/betterstack/env';
+import { createConsolePlugin } from './plugins/console';
+import { shouldEnableConsole } from './shared';
+
+import type { ObservabilityManager } from './core/manager';
+
+/**
+ * Create auto-configured observability for Next.js edge runtime
+ * Note: Sentry is not included here as it requires Node.js APIs
+ */
+export async function createEdgeObservability() {
+  const builder = ObservabilityBuilder.create().withAutoInitialize(false); // Manual init in edge runtime
+
+  // Console logging control using shared utility
+  const enableConsole = shouldEnableConsole(
+    env.NEXT_PUBLIC_NODE_ENV,
+    env.NEXT_PUBLIC_OBSERVABILITY_CONSOLE_ENABLED,
+    env.NEXT_PUBLIC_OBSERVABILITY_DEBUG,
+  );
+
+  // Always add console plugin, control via enabled flag
+  builder.withPlugin(
+    createConsolePlugin({
+      prefix: '[Next.js Edge]',
+      enabled: enableConsole,
+    }),
+  );
+
+  // Auto-activate Better Stack if source token is provided (uses fetch API)
+  const betterStackToken =
+    betterStackEnv.BETTER_STACK_SOURCE_TOKEN ??
+    betterStackEnv.BETTERSTACK_SOURCE_TOKEN ??
+    betterStackEnv.LOGTAIL_SOURCE_TOKEN;
+
+  if (betterStackToken) {
+    builder.withPlugin(
+      createBetterStackPlugin({
+        sourceToken: betterStackToken,
+      }),
+    );
+  }
+
+  // Note: Sentry requires Node.js APIs and isn't available in edge runtime
+  // Better Stack is the recommended solution for edge runtime logging
+
+  return builder.build();
+}
+
+// Lazy initialization for the observability instance using promise-based singleton
+let initializationPromise: Promise<ObservabilityManager> | null = null;
+
+/**
+ * Get or create the observability instance
+ * Uses promise-based singleton pattern to prevent race conditions in concurrent scenarios
+ * @returns Promise resolving to the ObservabilityManager instance
+ */
+export async function getObservability(): Promise<ObservabilityManager> {
+  if (!initializationPromise) {
+    initializationPromise = (async () => {
+      try {
+        return await createEdgeObservability();
+      } catch (error) {
+        // Reset cached promise on failure so callers can retry
+        initializationPromise = null;
+        throw error;
+      }
+    })();
+  }
+  return initializationPromise;
+}
+
+// Export types and utilities
+export * from './core/types';
+export type {
+  ObservabilityPlugin,
+  ObservabilityServerPlugin,
+  PluginFactory,
+  PluginLifecycle,
+} from './core/plugin';
+export { createObservability } from './factory';
+export { ObservabilityBuilder } from './factory/builder';
+
+// Re-export edge-compatible plugins only (explicit to avoid duplicate ObservabilityPlugin/ObservabilityServerPlugin)
+export { BetterStackPlugin, createBetterStackPlugin, env, safeEnv } from './plugins/betterstack';
+export type { BetterStackPluginConfig } from './plugins/betterstack';
+export {
+  ConsolePlugin,
+  ConsoleServerPlugin,
+  createConsolePlugin,
+  createConsoleServerPlugin,
+} from './plugins/console';
+export type { ConsolePluginConfig } from './plugins/console';
+
+// Legacy function for backward compatibility (no-op)
+/**
+ * @deprecated Configuration now happens through the observability system
+ */
+export const configureLogger = () => {
+  // No-op: Configuration now happens through the observability system
+};
+
+// Re-export type
+export type LogContext = Record<string, unknown>;

package/src/server-next.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Next.js server-specific observability export
+ * Next.js server-specific observability export
+ */
+
+import { env } from '../env';
+
+import { ObservabilityBuilder } from './factory/builder';
+import { createBetterStackPlugin } from './plugins/betterstack';
+import { env as betterStackEnv } from './plugins/betterstack/env';
+import { createConsoleServerPlugin } from './plugins/console';
+import { createSentryPlugin } from './plugins/sentry';
+import { env as sentryEnv } from './plugins/sentry/env';
+import { shouldEnableConsole } from './shared';
+
+import type { ObservabilityManager } from './core/manager';
+
+/**
+ * Create auto-configured observability for Next.js server
+ */
+export async function createServerObservability() {
+  const builder = ObservabilityBuilder.create();
+
+  // Console logging control using shared utility
+  const enableConsole = shouldEnableConsole(
+    env.NEXT_PUBLIC_NODE_ENV,
+    env.NEXT_PUBLIC_OBSERVABILITY_CONSOLE_ENABLED,
+    env.NEXT_PUBLIC_OBSERVABILITY_DEBUG,
+  );
+
+  // Always add console plugin, control via enabled flag
+  builder.withPlugin(
+    createConsoleServerPlugin({
+      prefix: '[Next.js Server]',
+      enabled: enableConsole,
+    }),
+  );
+
+  // Auto-activate Sentry if DSN is provided
+  // Only use client-accessible DSN for auto-detection to avoid server/client boundary issues
+  const sentryDSN = sentryEnv.NEXT_PUBLIC_SENTRY_DSN;
+  if (sentryDSN) {
+    const sentry = createSentryPlugin({
+      dsn: sentryDSN,
+    });
+    await sentry.initialize();
+    builder.withPlugin(sentry);
+  }
+
+  // Auto-activate Better Stack if source token is provided
+  const betterStackToken =
+    betterStackEnv.BETTER_STACK_SOURCE_TOKEN ??
+    betterStackEnv.BETTERSTACK_SOURCE_TOKEN ??
+    betterStackEnv.LOGTAIL_SOURCE_TOKEN;
+
+  if (betterStackToken) {
+    const betterstack = createBetterStackPlugin({
+      sourceToken: betterStackToken,
+    });
+    await betterstack.initialize();
+    builder.withPlugin(betterstack);
+  }
+
+  return builder.build();
+}
+
+// Lazy initialization for the observability instance using promise-based singleton
+let initializationPromise: Promise<ObservabilityManager> | null = null;
+
+/**
+ * Get or create the observability instance
+ * Uses promise-based singleton pattern to prevent race conditions in concurrent scenarios
+ * @returns Promise resolving to the ObservabilityManager instance
+ */
+export async function getObservability(): Promise<ObservabilityManager> {
+  if (!initializationPromise) {
+    initializationPromise = (async () => {
+      try {
+        return await createServerObservability();
+      } catch (error) {
+        // Reset cached promise on failure so callers can retry
+        initializationPromise = null;
+        throw error;
+      }
+    })();
+  }
+  return initializationPromise;
+}
+
+// Export types and utilities
+export * from './core/types';
+export { createObservability } from './factory';
+export { ObservabilityBuilder } from './factory/builder';
+export { ObservabilityManager } from "./factory";
+
+// Re-export plugins for direct access (excluding conflicting exports)
+export { BetterStackPlugin } from './plugins/betterstack';
+export { ConsolePlugin } from './plugins/console';
+export { SentryPlugin } from './plugins/sentry';
+export { SentryMicroFrontendPlugin } from './plugins/sentry-microfrontend';
+
+// Re-export plugin-specific types with aliases to avoid conflicts
+// Removed for Rollup compatibility
+// Removed for Rollup compatibility
+
+// Legacy function for backward compatibility (no-op)
+/**
+ * @deprecated Configuration now happens through the observability system
+ */
+export const configureLogger = (): void => {
+  // No-op: Configuration now happens through the observability system
+};
+
+// Re-export type - removed for Rollup compatibility