@od-oneapp/observability 2026.1.1301

package/src/plugins/sentry/types.ts

@@ -0,0 +1,252 @@
+/**
+ * @fileoverview Sentry tracing type definitions
+ * Sentry tracing type definitions
+ */
+
+/**
+ * Transaction context for starting a new transaction
+ */
+export interface TransactionContext {
+  name: string;
+  op?: string;
+  tags?: Record<string, string>;
+  data?: Record<string, any>;
+  startTimestamp?: number;
+  parentSpanId?: string;
+  parentSampled?: boolean;
+  trimEnd?: boolean;
+  metadata?: {
+    source?: 'custom' | 'route' | 'url';
+    [key: string]: any;
+  };
+}
+
+/**
+ * Span context for creating child spans
+ */
+export interface SpanContext {
+  name: string;
+  op?: string;
+  description?: string;
+  tags?: Record<string, string>;
+  data?: Record<string, any>;
+  startTimestamp?: number;
+  status?: SpanStatus;
+  origin?: string;
+  attributes?: Record<string, any>;
+}
+
+/**
+ * Span status values
+ */
+export type SpanStatus =
+  | 'ok'
+  | 'cancelled'
+  | 'internal_error'
+  | 'invalid_argument'
+  | 'deadline_exceeded'
+  | 'not_found'
+  | 'already_exists'
+  | 'permission_denied'
+  | 'resource_exhausted'
+  | 'failed_precondition'
+  | 'aborted'
+  | 'out_of_range'
+  | 'unimplemented'
+  | 'unavailable'
+  | 'data_loss'
+  | 'unauthenticated';
+
+/**
+ * Transaction interface
+ */
+export interface Transaction {
+  name: string;
+  spanId: string;
+  traceId: string;
+  startTimestamp: number;
+  tags: Record<string, string>;
+  data: Record<string, any>;
+
+  // Methods
+  setName(name: string): void;
+  setTag(key: string, value: string | number | boolean | null): void;
+  setData(key: string, value: any): void;
+  setStatus(status: SpanStatus): void;
+  setHttpStatus(httpStatus: number): void;
+  setMeasurement(name: string, value: number, unit?: string): void;
+  finish(endTimestamp?: number): void;
+  startChild(spanContext?: SpanContext): Span;
+  toTraceparent(): string;
+  toContext(): TransactionContext;
+}
+
+/**
+ * Span interface
+ */
+export interface Span {
+  spanId: string;
+  traceId: string;
+  parentSpanId?: string;
+  op?: string;
+  description?: string;
+  startTimestamp: number;
+  tags: Record<string, string>;
+  data: Record<string, any>;
+
+  // Methods
+  setTag(key: string, value: string | number | boolean | null): void;
+  setData(key: string, value: any): void;
+  setStatus(status: SpanStatus): void;
+  setHttpStatus(httpStatus: number): void;
+  finish(endTimestamp?: number): void;
+  startChild(spanContext?: SpanContext): Span;
+  isRecording(): boolean;
+}
+
+/**
+ * Scope interface for managing context
+ */
+export interface Scope {
+  setTag(key: string, value: string | number | boolean | null): void;
+  setTags(tags: Record<string, string | number | boolean | null>): void;
+  setContext(key: string, context: Record<string, any> | null): void;
+  setUser(user: Record<string, any> | null): void;
+  setLevel(level: SeverityLevel): void;
+  setFingerprint(fingerprint: string[]): void;
+  setRequestSession(requestSession?: RequestSession): void;
+  setPropagationContext(context: PropagationContext): void;
+  clear(): void;
+  addBreadcrumb(breadcrumb: SentryBreadcrumb, maxBreadcrumbs?: number): void;
+  clearBreadcrumbs(): void;
+  setSpan(span: Span | undefined): void;
+  getSpan(): Span | undefined;
+  setTransaction(transaction: Transaction | undefined): void;
+  getTransaction(): Transaction | undefined;
+}
+
+/**
+ * Hub interface for managing scopes and clients
+ */
+export interface Hub {
+  getClient(): any;
+  getScope(): Scope;
+  configureScope(callback: (scope: Scope) => void): void;
+  pushScope(): Scope;
+  popScope(): boolean;
+  withScope(callback: (scope: Scope) => void): void;
+  startTransaction(context: TransactionContext, customSamplingContext?: any): Transaction;
+  startSpan(context: SpanContext): Span;
+}
+
+/**
+ * Propagation context for distributed tracing
+ */
+export interface PropagationContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+  dsc?: DynamicSamplingContext;
+}
+
+/**
+ * Dynamic sampling context
+ */
+export interface DynamicSamplingContext {
+  trace_id: string;
+  public_key: string;
+  sample_rate?: string;
+  release?: string;
+  environment?: string;
+  transaction?: string;
+  user_segment?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Traceparent data extracted from headers
+ */
+export interface TraceparentData {
+  traceId?: string;
+  parentSpanId?: string;
+  parentSampled?: boolean;
+  baggage?: Record<string, string>;
+}
+
+/**
+ * Sentry-specific breadcrumb interface
+ * Note: Use core Breadcrumb type for plugin-agnostic code.
+ * This type matches Sentry SDK's expected format.
+ */
+export interface SentryBreadcrumb {
+  type?: string;
+  level?: SeverityLevel;
+  category?: string;
+  message?: string;
+  data?: Record<string, any>;
+  timestamp?: number;
+}
+
+/**
+ * Severity levels
+ */
+export type SeverityLevel = 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug';
+
+/**
+ * Request session status
+ */
+export interface RequestSession {
+  status?: 'ok' | 'errored' | 'crashed';
+}
+
+/**
+ * Sampling context for trace sampling decisions
+ */
+export interface SamplingContext {
+  transactionContext: TransactionContext;
+  parentSampled?: boolean;
+  request?: any;
+  location?: {
+    href?: string;
+    pathname?: string;
+    search?: string;
+    hash?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Custom sampling function type
+ */
+export type TraceSampler = (samplingContext: SamplingContext) => number | boolean;
+
+/**
+ * Measurement units
+ */
+export type MeasurementUnit =
+  | 'nanosecond'
+  | 'microsecond'
+  | 'millisecond'
+  | 'second'
+  | 'minute'
+  | 'hour'
+  | 'day'
+  | 'week'
+  | 'bit'
+  | 'byte'
+  | 'kilobyte'
+  | 'kibibyte'
+  | 'megabyte'
+  | 'mebibyte'
+  | 'gigabyte'
+  | 'gibibyte'
+  | 'terabyte'
+  | 'tebibyte'
+  | 'petabyte'
+  | 'pebibyte'
+  | 'exabyte'
+  | 'exbibyte'
+  | 'ratio'
+  | 'percent'
+  | 'none';

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

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Environment configuration for Sentry Micro Frontend Plugin
+ * Environment configuration for Sentry Micro Frontend Plugin
+ */
+
+import { logWarn } from '@repo/shared/logger';
+import { createEnv } from '@t3-oss/env-core';
+import { z } from 'zod/v4';
+
+/**
+ * Environment configuration specific to Sentry micro frontend functionality
+ */
+export const env = createEnv({
+  server: {
+    // Backstage app-specific DSNs for server-side
+    SENTRY_DSN_CMS: z.string().url().optional(),
+    SENTRY_DSN_WORKFLOWS: z.string().url().optional(),
+    SENTRY_DSN_AUTHMGMT: z.string().url().optional(),
+
+    // Micro frontend configuration
+    SENTRY_MICROFRONTEND_MODE: z.enum(['host', 'child', 'standalone']).optional(),
+    SENTRY_MICROFRONTEND_ZONE: z.string().optional(),
+
+    // Feature toggles
+    SENTRY_MICROFRONTEND_ENABLED: z.boolean().optional(),
+    SENTRY_MICROFRONTEND_MULTIPLEXED_TRANSPORT: z.boolean().optional(),
+  },
+  client: {
+    // Backstage app-specific DSNs for client-side
+    NEXT_PUBLIC_SENTRY_DSN_CMS: z.string().url().optional(),
+    NEXT_PUBLIC_SENTRY_DSN_WORKFLOWS: z.string().url().optional(),
+    NEXT_PUBLIC_SENTRY_DSN_AUTHMGMT: z.string().url().optional(),
+
+    // Client-side micro frontend configuration
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_MODE: z.enum(['host', 'child', 'standalone']).optional(),
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_ZONE: z.string().optional(),
+
+    // Feature toggles
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_ENABLED: z.boolean().optional(),
+  },
+  clientPrefix: 'NEXT_PUBLIC_',
+  runtimeEnv: process.env,
+  skipValidation: process.env.SKIP_ENV_VALIDATION === 'true' || process.env.NODE_ENV === 'test',
+  emptyStringAsUndefined: true,
+  onInvalidAccess: (variable: string) => {
+    throw new Error(
+      `❌ Attempted to access a server-side environment variable on the client: ${variable}`,
+    );
+  },
+  onValidationError: error => {
+    // Non-critical plugin, warn but don't throw
+    logWarn('Sentry Micro Frontend Plugin env validation failed', { error });
+    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 for Sentry
+ * micro frontend configuration.
+ *
+ * @returns Environment object with Sentry micro frontend configuration values
+ */
+export function safeEnv() {
+  if (env) {
+    return env;
+  }
+
+  // Fallback for non-Next.js contexts
+  return {
+    // Server
+    SENTRY_DSN_CMS: process.env.SENTRY_DSN_CMS,
+    SENTRY_DSN_WORKFLOWS: process.env.SENTRY_DSN_WORKFLOWS,
+    SENTRY_DSN_AUTHMGMT: process.env.SENTRY_DSN_AUTHMGMT,
+    SENTRY_MICROFRONTEND_MODE: process.env.SENTRY_MICROFRONTEND_MODE as
+      | 'host'
+      | 'child'
+      | 'standalone'
+      | undefined,
+    SENTRY_MICROFRONTEND_APP:
+      process.env.SENTRY_MICROFRONTEND_APP ?? process.env.SENTRY_MICROFRONTEND_ZONE,
+    SENTRY_MICROFRONTEND_ENABLED: process.env.SENTRY_MICROFRONTEND_ENABLED === 'true',
+    SENTRY_MICROFRONTEND_MULTIPLEXED_TRANSPORT:
+      process.env.SENTRY_MICROFRONTEND_MULTIPLEXED_TRANSPORT === 'true',
+
+    // Client
+    NEXT_PUBLIC_SENTRY_DSN_CMS: process.env.NEXT_PUBLIC_SENTRY_DSN_CMS,
+    NEXT_PUBLIC_SENTRY_DSN_WORKFLOWS: process.env.NEXT_PUBLIC_SENTRY_DSN_WORKFLOWS,
+    NEXT_PUBLIC_SENTRY_DSN_AUTHMGMT: process.env.NEXT_PUBLIC_SENTRY_DSN_AUTHMGMT,
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_MODE: process.env.NEXT_PUBLIC_SENTRY_MICROFRONTEND_MODE as
+      | 'host'
+      | 'child'
+      | 'standalone'
+      | undefined,
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_APP:
+      process.env.NEXT_PUBLIC_SENTRY_MICROFRONTEND_APP ??
+      process.env.NEXT_PUBLIC_SENTRY_MICROFRONTEND_ZONE,
+    NEXT_PUBLIC_SENTRY_MICROFRONTEND_ENABLED:
+      process.env.NEXT_PUBLIC_SENTRY_MICROFRONTEND_ENABLED === 'true',
+  };
+}
+
+export type Env = typeof env;

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Sentry Micro Frontend Plugin
+ * Sentry Micro Frontend Plugin
+ *
+ * Provides specialized Sentry integration for micro frontend architectures.
+ * Supports both host and child modes with automatic parent detection.
+ */
+
+export { createMultiplexedTransport } from './multiplexed-transport';
+export { SentryMicroFrontendPlugin, createSentryMicroFrontendPlugin } from './plugin';
+export type { BackstageAppConfig, MicroFrontendMode, SentryMicroFrontendConfig } from './types';
+export { createBackstageScope, detectCurrentBackstageApp, isHostEnvironment } from './utils';

package/src/plugins/sentry-microfrontend/multiplexed-transport.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Multiplexed transport utilities for Sentry Micro Frontend Plugin
+ * Multiplexed transport utilities for Sentry Micro Frontend Plugin
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import type { BackstageAppConfig } from './types';
+
+/**
+ * Create a multiplexed transport that routes events to different Sentry projects.
+ *
+ * Creates a Sentry transport that routes events to different DSNs based on the
+ * backstageApp information in the event. Supports edge runtime environments.
+ *
+ * @param backstage - Array of backstage app configurations with DSNs
+ * @param fallbackDsn - Optional fallback DSN if no backstageApp match is found
+ * @param sentryClient - Optional Sentry client instance (defaults to global Sentry)
+ * @returns Multiplexed transport instance, or undefined if Sentry is not available
+ */
+
+export function createMultiplexedTransport(
+  backstage: BackstageAppConfig[],
+  fallbackDsn?: string,
+
+  sentryClient?: any,
+): any {
+  // Import Sentry dynamically or use provided client (edge runtime compatible)
+  const Sentry =
+    sentryClient !== undefined
+      ? sentryClient
+      : typeof globalThis !== 'undefined'
+        ? (globalThis as any).Sentry
+        : null;
+
+  if (!Sentry?.makeMultiplexedTransport || !Sentry.makeFetchTransport) {
+    logWarn('Sentry multiplexed transport not available');
+    return undefined;
+  }
+
+  return Sentry.makeMultiplexedTransport(Sentry.makeFetchTransport, (args: any) => {
+    const event = args.getEvent();
+
+    if (!event) {
+      return [];
+    }
+
+    // Extract backstageApp information from various sources
+    const backstageApp =
+      event.tags?.backstageApp ??
+      event.extra?.backstageApp ??
+      event.contexts?.microFrontend?.backstageApp;
+
+    if (backstageApp) {
+      // Find backstageApp configuration
+      const backstageAppConfig = backstage.find(z => z.name === backstageApp);
+
+      if (backstageAppConfig?.dsn) {
+        // Route to backstageApp-specific DSN
+
+        const envelope: any[] = [
+          {
+            dsn: backstageAppConfig.dsn,
+            release: backstageAppConfig.release ?? event.release,
+          },
+        ];
+
+        // Add backstageApp-specific tags if configured
+        if (backstageAppConfig.tags && event.tags) {
+          Object.assign(event.tags, backstageAppConfig.tags);
+        }
+
+        return envelope;
+      }
+    }
+
+    // Use fallback DSN if provided
+    if (fallbackDsn) {
+      return [{ dsn: fallbackDsn }];
+    }
+
+    // Let the default DSN handle it
+    return [];
+  });
+}
+
+/**
+ * Create a transport matcher function for more complex routing logic.
+ *
+ * Creates a matcher function that can be used with Sentry's multiplexed transport
+ * to route events based on custom logic, including stack frame analysis.
+ *
+ * @param backstage - Array of backstage app configurations
+ * @param customMatcher - Optional custom matcher function to extract backstageApp from event
+ * @returns Matcher function that returns an array of transport configurations
+ */
+export function createTransportMatcher(
+  backstage: BackstageAppConfig[],
+
+  customMatcher?: (event: any) => string | undefined,
+): (args: any) => any[] {
+  return (args: any) => {
+    const event = args.getEvent();
+
+    if (!event) {
+      return [];
+    }
+
+    // Use custom matcher if provided
+    let backstageApp: string | undefined;
+    if (customMatcher) {
+      backstageApp = customMatcher(event);
+    }
+
+    // Fall back to default backstageApp detection
+    backstageApp ??=
+      event.tags?.backstageApp ??
+      event.extra?.backstageApp ??
+      event.contexts?.microFrontend?.backstageApp;
+
+    // Try to detect backstageApp from stack frames
+    if (!backstageApp && event.exception?.values?.[0]?.stacktrace?.frames) {
+      const { frames } = event.exception.values[0].stacktrace;
+      for (const frame of frames) {
+        if (frame.filename) {
+          // Check if filename contains backstageApp hints
+          if (frame.filename.includes('/cms/')) {
+            backstageApp = 'cms';
+            break;
+          } else if (frame.filename.includes('/workflows/')) {
+            backstageApp = 'workflows';
+            break;
+          } else if (frame.filename.includes('/authmgmt/')) {
+            backstageApp = 'authmgmt';
+            break;
+          }
+        }
+      }
+    }
+
+    if (backstageApp) {
+      const backstageAppConfig = backstage.find(z => z.name === backstageApp);
+      if (backstageAppConfig?.dsn) {
+        return [
+          {
+            dsn: backstageAppConfig.dsn,
+            release: backstageAppConfig.release,
+          },
+        ];
+      }
+    }
+
+    return [];
+  };
+}
+
+/**
+ * Enhance an event with Backstage app information before sending.
+ *
+ * Adds backstageApp tags, context, and extra data to a Sentry event.
+ * This ensures events are properly tagged for micro frontend routing.
+ *
+ * @param event - Sentry event to enhance
+ * @param backstageApp - Name of the backstage app
+ * @param additionalContext - Optional additional context to add
+ * @returns Enhanced event with backstageApp information
+ */
+
+export function enhanceEventWithBackstageApp(
+  event: any,
+  backstageApp: string,
+
+  additionalContext?: Record<string, any>,
+): any {
+  // Add backstageApp tag
+  event.tags ??= {};
+  event.tags.backstageApp = backstageApp;
+  event.tags.microFrontend = true;
+
+  // Add backstageApp context
+  event.contexts ??= {};
+  event.contexts.microFrontend = {
+    backstageApp,
+    timestamp: new Date().toISOString(),
+    ...additionalContext,
+  };
+
+  // Add backstageApp to extra for backward compatibility
+  event.extra ??= {};
+  event.extra.backstageApp = backstageApp;
+
+  return event;
+}
+
+/**
+ * Create a beforeSend hook that adds backstageApp information.
+ *
+ * Creates a Sentry beforeSend hook that enhances events with backstageApp information
+ * before they are sent. Can wrap an existing beforeSend hook.
+ *
+ * @param backstageApp - Name of the backstage app
+ * @param originalBeforeSend - Optional original beforeSend hook to wrap
+ * @returns beforeSend hook function
+ */
+export function createBackstageBeforeSend(
+  backstageApp: string,
+
+  originalBeforeSend?: (event: any, hint: any) => any,
+): (event: any, hint: any) => any {
+  return (event: any, hint: any) => {
+    // Enhance with backstageApp information
+    enhanceEventWithBackstageApp(event, backstageApp);
+
+    // Call original beforeSend if provided
+    if (originalBeforeSend) {
+      return originalBeforeSend(event, hint);
+    }
+
+    return event;
+  };
+}