@od-oneapp/observability 2026.1.1301

package/src/plugins/betterstack/plugin.ts

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview Better Stack (Logtail) plugin implementation
+ * Better Stack (Logtail) plugin implementation
+ * Updated to use official @logtail packages
+ */
+
+import { logError, logWarn } from '@repo/shared/logger';
+import type { ObservabilityServerPlugin } from '../../core/plugin';
+import type {
+  Breadcrumb,
+  LogLevel,
+  ObservabilityContext,
+  ObservabilityUser,
+} from '../../core/types';
+import { safeEnv } from './env';
+
+/**
+ * Maximum number of breadcrumbs to include in error/message context
+ * Limits context size to prevent excessive data transmission
+ */
+const MAX_BREADCRUMBS_IN_CONTEXT = 10;
+
+/**
+ * Maximum number of breadcrumbs to store in memory
+ * Prevents unbounded memory growth while maintaining useful history
+ */
+const MAX_BREADCRUMBS_STORED = 100;
+
+/**
+ * Minimal Logtail interface for common methods across all @logtail packages
+ */
+interface LogtailClient {
+  info(message: string, data?: any): void;
+  warn(message: string, data?: any): void;
+  error(message: string, data?: any): void;
+  debug(message: string, data?: any): void;
+  flush(): Promise<void>;
+}
+
+/**
+ * Better Stack plugin configuration
+ */
+export interface BetterStackPluginConfig {
+  /**
+   * The @logtail package to use (e.g., '@logtail/js', '@logtail/next')
+   * If not provided, the plugin will auto-detect based on environment
+   */
+  logtailPackage?: string;
+
+  // Core configuration options
+  sourceToken?: string;
+  endpoint?: string;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'off';
+  enabled?: boolean;
+
+  // Advanced options
+  batchInterval?: number;
+  batchSize?: number;
+  retryCount?: number;
+  retryBackoff?: boolean;
+  middleware?: any[];
+}
+
+/**
+ * Better Stack plugin implementation using official @logtail packages
+ */
+/**
+ * Better Stack (Logtail) plugin implementation.
+ *
+ * Integrates Better Stack logging service into the observability system.
+ * Uses official @logtail packages (@logtail/js or @logtail/next) for unified
+ * logging across environments.
+ */
+export class BetterStackPlugin<
+  T extends LogtailClient = LogtailClient,
+> implements ObservabilityServerPlugin<T> {
+  name = 'betterstack';
+  enabled: boolean;
+  protected client: T | undefined;
+  protected initialized = false;
+  protected logtailPackage: string;
+  protected currentUser: ObservabilityUser | null = null;
+  protected breadcrumbs: Breadcrumb[] = [];
+  protected breadcrumbIndex = 0;
+  protected config: BetterStackPluginConfig;
+
+  /**
+   * Create a new BetterStackPlugin instance.
+   *
+   * @param config - Better Stack plugin configuration
+   */
+  constructor(config: BetterStackPluginConfig = {}) {
+    this.config = config;
+    const env = safeEnv();
+    // Auto-enable if token is provided
+    const hasToken =
+      config.sourceToken ??
+      env.BETTER_STACK_SOURCE_TOKEN ??
+      env.BETTERSTACK_SOURCE_TOKEN ??
+      env.LOGTAIL_SOURCE_TOKEN ??
+      env.NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN ??
+      env.NEXT_PUBLIC_BETTERSTACK_TOKEN ??
+      env.NEXT_PUBLIC_LOGTAIL_TOKEN;
+    this.enabled = config.enabled ?? Boolean(hasToken);
+
+    // Determine Logtail package to use
+    this.logtailPackage = config.logtailPackage ?? this.detectLogtailPackage();
+  }
+
+  /**
+   * Detect which Logtail package to use based on the runtime environment.
+   *
+   * @returns Package name ('@logtail/next' for Next.js, '@logtail/js' otherwise)
+   */
+  private detectLogtailPackage(): string {
+    // Next.js environments use Next.js package
+    if (process.env.NEXT_RUNTIME) {
+      return '@logtail/next';
+    }
+    // All other environments use the unified js package (bundles both node and browser)
+    return '@logtail/js';
+  }
+
+  getClient(): T | undefined {
+    return this.client;
+  }
+
+  /**
+   * Get safe environment access (for testing/mocking).
+   *
+   * @returns Environment configuration object
+   */
+  protected getSafeEnv() {
+    return safeEnv();
+  }
+
+  async initialize(config?: BetterStackPluginConfig): Promise<void> {
+    if (this.initialized || !this.enabled) return;
+
+    const env = safeEnv();
+    const mergedConfig = { ...this.config, ...config };
+
+    // Get source token with priority: config > new env vars > legacy env vars
+    const sourceToken =
+      mergedConfig.sourceToken ??
+      env.BETTER_STACK_SOURCE_TOKEN ??
+      env.NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN ??
+      env.LOGTAIL_SOURCE_TOKEN ??
+      env.BETTERSTACK_SOURCE_TOKEN ??
+      env.NEXT_PUBLIC_LOGTAIL_TOKEN ??
+      env.NEXT_PUBLIC_BETTERSTACK_TOKEN;
+
+    if (!sourceToken) {
+      logWarn('Better Stack plugin: No source token provided, skipping initialization');
+      this.enabled = false;
+      return;
+    }
+
+    try {
+      // Dynamic import of the specified Logtail package
+      const LogtailModule = await import(/* webpackIgnore: true */ this.logtailPackage);
+
+      // Handle different export patterns
+      const LogtailClass = LogtailModule.default ?? LogtailModule.Logtail ?? LogtailModule;
+
+      if (!LogtailClass) {
+        logError(`Better Stack plugin: Could not find Logtail class in ${this.logtailPackage}`, {
+          logtailPackage: this.logtailPackage,
+        });
+        this.enabled = false;
+        return;
+      }
+
+      // Build configuration object
+      const logtailConfig: any = {
+        sourceToken,
+      };
+
+      // Add optional configuration
+      if (
+        mergedConfig.endpoint ??
+        env.BETTER_STACK_INGESTING_URL ??
+        env.NEXT_PUBLIC_BETTER_STACK_INGESTING_URL
+      ) {
+        logtailConfig.endpoint =
+          mergedConfig.endpoint ??
+          env.BETTER_STACK_INGESTING_URL ??
+          env.NEXT_PUBLIC_BETTER_STACK_INGESTING_URL;
+      }
+
+      // Initialize the client
+      this.client = new LogtailClass(logtailConfig) as T;
+
+      this.initialized = true;
+    } catch (error) {
+      logError(`Failed to import Logtail package '${this.logtailPackage}'`, {
+        error,
+        logtailPackage: this.logtailPackage,
+      });
+      this.enabled = false;
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.client && this.initialized) {
+      await this.client.flush();
+      this.initialized = false;
+    }
+  }
+
+  captureException(error: Error | unknown, context?: ObservabilityContext): void {
+    if (!this.enabled || !this.client) return;
+
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+
+    // Build structured data
+    const data = {
+      error: {
+        name: errorObj.name,
+        message: errorObj.message,
+        stack: errorObj.stack,
+      },
+      context: context?.extra,
+      tags: context?.tags,
+      user: context?.user ?? this.currentUser,
+      breadcrumbs: this.getRecentBreadcrumbs(MAX_BREADCRUMBS_IN_CONTEXT),
+    };
+
+    this.client.error(errorObj.message, data);
+  }
+
+  captureMessage(message: string, level: LogLevel = 'info', context?: ObservabilityContext): void {
+    if (!this.enabled || !this.client) return;
+
+    // Build structured data
+    const data = {
+      level,
+      context: context?.extra,
+      tags: context?.tags,
+      user: context?.user ?? this.currentUser,
+      breadcrumbs: this.getRecentBreadcrumbs(MAX_BREADCRUMBS_IN_CONTEXT),
+    };
+
+    // Map log levels to Logtail methods
+    switch (level) {
+      case 'debug':
+        this.client.debug(message, data);
+        break;
+      case 'warning':
+        this.client.warn(message, data);
+        break;
+      case 'error':
+        this.client.error(message, data);
+        break;
+      case 'info':
+      default:
+        this.client.info(message, data);
+        break;
+    }
+  }
+
+  setUser(user: ObservabilityUser | null): void {
+    if (!this.enabled) return;
+    this.currentUser = user;
+  }
+
+  addBreadcrumb(breadcrumb: Breadcrumb): void {
+    if (!this.enabled) return;
+
+    const enriched = {
+      ...breadcrumb,
+      timestamp: breadcrumb.timestamp ?? Date.now() / 1000,
+    };
+
+    // Use circular buffer to avoid array reallocation
+    if (this.breadcrumbs.length < MAX_BREADCRUMBS_STORED) {
+      this.breadcrumbs.push(enriched);
+    } else {
+      // Overwrite oldest entry (circular buffer)
+      this.breadcrumbs[this.breadcrumbIndex] = enriched;
+      this.breadcrumbIndex = (this.breadcrumbIndex + 1) % MAX_BREADCRUMBS_STORED;
+    }
+  }
+
+  /**
+   * Get the most recent breadcrumbs in chronological order
+   * @param count - Number of breadcrumbs to retrieve
+   * @returns Array of recent breadcrumbs
+   */
+  private getRecentBreadcrumbs(count: number): Breadcrumb[] {
+    const { length } = this.breadcrumbs;
+    if (length === 0) return [];
+    if (length <= count) return this.breadcrumbs.slice();
+
+    // If buffer is not full yet, return last N items from end of array
+    if (length < MAX_BREADCRUMBS_STORED) {
+      return this.breadcrumbs.slice(length - count);
+    }
+
+    // Circular buffer logic:
+    // - When the buffer is full, `this.breadcrumbIndex` points to the oldest entry (the next to be overwritten).
+    // - The most recent breadcrumb is at index `(this.breadcrumbIndex - 1 + length) % length`.
+    // - To get the last `count` breadcrumbs in chronological order, we start at
+    //   `(this.breadcrumbIndex - count + length) % length` and read `count` entries, wrapping around as needed.
+    // - This ensures we always get the correct slice, even if the buffer has wrapped around.
+    const result: Breadcrumb[] = [];
+    const start = (this.breadcrumbIndex - count + length) % length;
+
+    for (let i = 0; i < count; i++) {
+      const index = (start + i) % length;
+      const breadcrumb = this.breadcrumbs[index];
+      if (breadcrumb) {
+        result.push(breadcrumb);
+      }
+    }
+
+    return result;
+  }
+
+  withScope(callback: (scope: any) => void): void {
+    if (!this.enabled) return;
+
+    try {
+      // Simple scope implementation
+      const scope = {
+        setContext: (_key: string, _context: unknown) => {
+          // Could store this for next log entry
+        },
+        setUser: (user: ObservabilityUser | null) => {
+          this.setUser(user);
+        },
+      };
+      callback(scope);
+    } catch {
+      // Gracefully handle scope errors
+    }
+  }
+
+  async flush(_timeout?: number): Promise<boolean> {
+    if (!this.enabled || !this.client) return true;
+
+    try {
+      await this.client.flush();
+      return true;
+    } catch (error) {
+      logError('Better Stack flush error', { error });
+      return false;
+    }
+  }
+}
+
+/**
+ * Factory function to create a Better Stack plugin.
+ *
+ * Creates a configured BetterStackPlugin instance with optional configuration.
+ * Auto-detects the appropriate @logtail package based on the environment.
+ *
+ * @param config - Optional Better Stack plugin configuration
+ * @returns BetterStackPlugin instance
+ *
+ * @example
+ * ```typescript
+ * const betterstack = createBetterStackPlugin({
+ *   sourceToken: '...',
+ *   logLevel: 'info',
+ * });
+ * ```
+ */
+export const createBetterStackPlugin = <T extends LogtailClient = LogtailClient>(
+  config?: BetterStackPluginConfig,
+): BetterStackPlugin<T> => {
+  return new BetterStackPlugin<T>(config);
+};

package/src/plugins/console/index.ts

@@ -0,0 +1,323 @@
+/**
+ * @fileoverview Console plugin for observability
+ * Console plugin for observability
+ * Simple logging implementation for development
+ */
+
+import { isBrowser } from '../../shared';
+
+import type {
+  ObservabilityPlugin,
+  ObservabilityServerPlugin,
+  PluginFactory,
+} from '../../core/plugin';
+import type {
+  Breadcrumb,
+  LogLevel,
+  ObservabilityContext,
+  ObservabilityUser,
+} from '../../core/types';
+
+/**
+ * Console plugin configuration
+ */
+export interface ConsolePluginConfig {
+  prefix?: string;
+  logLevel?: LogLevel;
+  enabled?: boolean;
+  colors?: boolean;
+}
+
+/**
+ * Console plugin implementation for browser environments
+ */
+/**
+ * Console plugin implementation for browser environments.
+ *
+ * Provides simple console logging with color support for development.
+ * Supports both browser (CSS colors) and Node.js (ANSI colors) environments.
+ */
+export class ConsolePlugin implements ObservabilityPlugin<Console> {
+  name = 'console';
+  enabled: boolean;
+  protected prefix: string;
+  private colors: boolean;
+  private isBrowser: boolean;
+
+  /**
+   * Create a new ConsolePlugin instance.
+   *
+   * @param config - Console plugin configuration
+   */
+  constructor(config: ConsolePluginConfig = {}) {
+    this.enabled = config.enabled ?? true;
+    this.prefix = config.prefix ?? '[Console]';
+    // Note: config.logLevel is accepted but not yet used (reserved for future log level filtering)
+    this.colors = config.colors ?? true;
+    this.isBrowser = isBrowser();
+  }
+
+  async initialize(): Promise<void> {
+    // Console doesn't need initialization
+  }
+
+  async shutdown(): Promise<void> {
+    // Console doesn't need shutdown
+  }
+
+  getClient(): Console | undefined {
+    return undefined; // Console has no client
+  }
+
+  captureException(error: Error | unknown, context?: ObservabilityContext): void {
+    if (!this.enabled) return;
+
+    try {
+      const contextData = this.formatContext(context);
+
+      if (this.colors && this.isBrowser) {
+        // Browser: Use CSS colors
+        console.error(
+          `%c${this.prefix} Error:`,
+          'color: red; font-weight: bold',
+          error,
+          contextData,
+        );
+      } else if (this.colors) {
+        // Node.js: Use ANSI codes
+        console.error(`\x1b[31m${this.prefix} Error:\x1b[0m`, error, contextData);
+      } else {
+        // No colors
+        console.error(`${this.prefix} Error:`, error, contextData);
+      }
+    } catch {
+      // Gracefully handle console errors
+    }
+  }
+
+  captureMessage(message: string, level: LogLevel = 'info', context?: ObservabilityContext): void {
+    if (!this.enabled) return;
+
+    try {
+      const contextData = this.formatContext(context);
+      const logMethod = this.getLogMethod(level);
+      const levelLabel = this.getLevelLabel(level);
+
+      if (this.colors && this.isBrowser) {
+        // Browser: Use CSS colors
+        const cssColor = this.getBrowserColorCSS(level);
+        (console[logMethod] as (...args: any[]) => void)(
+          `%c${this.prefix} ${levelLabel}:`,
+          cssColor,
+          message,
+          contextData,
+        );
+      } else if (this.colors) {
+        // Node.js: Use ANSI codes
+        const ansiColor = this.getAnsiColorCode(level);
+        (console[logMethod] as (...args: any[]) => void)(
+          `${ansiColor}${this.prefix} ${levelLabel}:\x1b[0m`,
+          message,
+          contextData,
+        );
+      } else {
+        // No colors
+        (console[logMethod] as (...args: any[]) => void)(
+          `${this.prefix} ${levelLabel}:`,
+          message,
+          contextData,
+        );
+      }
+    } catch {
+      // Gracefully handle console errors
+    }
+  }
+
+  setUser(user: ObservabilityUser | null): void {
+    if (!this.enabled) return;
+
+    try {
+      if (user === null) {
+        console.info(this.prefix, 'User cleared');
+      } else {
+        console.info(this.prefix, 'User set:', JSON.stringify(user));
+      }
+    } catch {
+      // Gracefully handle console errors
+    }
+  }
+
+  addBreadcrumb(breadcrumb: Breadcrumb): void {
+    if (!this.enabled) return;
+
+    try {
+      const enrichedBreadcrumb = {
+        ...breadcrumb,
+        timestamp: breadcrumb.timestamp ?? Date.now() / 1000,
+      };
+      console.log(this.prefix, 'Breadcrumb:', JSON.stringify(enrichedBreadcrumb));
+    } catch {
+      // Gracefully handle console errors
+    }
+  }
+
+  withScope(callback: (scope: any) => void): void {
+    if (!this.enabled) return;
+
+    try {
+      const scope = {
+        setContext: (key: string, context: unknown) => {
+          console.log(this.prefix, 'Context set:', key, JSON.stringify(context));
+        },
+        setUser: (user: ObservabilityUser | null) => {
+          this.setUser(user);
+        },
+      };
+      callback(scope);
+    } catch {
+      // Gracefully handle scope errors
+    }
+  }
+
+  async flush(): Promise<boolean> {
+    // Console doesn't need flushing
+    if (this.enabled) {
+      console.log(this.prefix, 'Flushed');
+    }
+    return true;
+  }
+
+  private formatContext(context?: ObservabilityContext): any {
+    if (!context) return {};
+
+    // Handle new format with explicit extra/tags structure
+    if (context.extra !== undefined || context.tags !== undefined) {
+      return {
+        context: context.extra,
+        tags: context.tags,
+      };
+    }
+
+    // Handle AI package format with operation/metadata structure
+    if ('operation' in context || 'metadata' in context) {
+      return {
+        context: context.metadata ?? {},
+        tags: { operation: context.operation },
+      };
+    }
+
+    // Handle any other context format - use as-is for context
+    return {
+      context,
+      tags: {},
+    };
+  }
+
+  /**
+   * Get CSS color style for browser console
+   * @param level - Log level
+   * @returns CSS style string
+   */
+  private getBrowserColorCSS(level: LogLevel): string {
+    const colorMap: Record<LogLevel, string> = {
+      debug: 'color: #00CED1; font-weight: bold', // Dark Cyan
+      info: 'color: #32CD32; font-weight: bold', // Lime Green
+      warning: 'color: #FFA500; font-weight: bold', // Orange
+      error: 'color: #DC143C; font-weight: bold', // Crimson
+    };
+    return colorMap[level] ?? 'color: inherit';
+  }
+
+  /**
+   * Get ANSI color code for Node.js terminal
+   * @param level - Log level
+   * @returns ANSI escape code
+   */
+  private getAnsiColorCode(level: LogLevel): string {
+    const colorMap: Record<LogLevel, string> = {
+      debug: '\x1b[36m', // Cyan
+      info: '\x1b[32m', // Green
+      warning: '\x1b[33m', // Yellow
+      error: '\x1b[31m', // Red
+    };
+    return colorMap[level] ?? '';
+  }
+
+  /**
+   * Get the console method name for a log level.
+   *
+   * @param level - Log level
+   * @returns Console method name ('debug', 'info', 'warn', or 'error')
+   */
+  private getLogMethod(level: LogLevel): keyof Console {
+    switch (level) {
+      case 'debug':
+        return 'debug';
+      case 'info':
+        return 'info';
+      case 'warning':
+        return 'warn';
+      case 'error':
+        return 'error';
+      default:
+        return 'info';
+    }
+  }
+
+  /**
+   * Get a human-readable label for a log level.
+   *
+   * @param level - Log level
+   * @returns Capitalized level label ('Debug', 'Info', 'Warning', 'Error')
+   */
+  private getLevelLabel(level: LogLevel): string {
+    switch (level) {
+      case 'debug':
+        return 'Debug';
+      case 'info':
+        return 'Info';
+      case 'warning':
+        return 'Warning';
+      case 'error':
+        return 'Error';
+      default:
+        return 'Info';
+    }
+  }
+}
+
+/**
+ * Console plugin implementation for server environments
+ * Inherits flush() from ConsolePlugin - no override needed
+ */
+export class ConsoleServerPlugin
+  extends ConsolePlugin
+  implements ObservabilityServerPlugin<Console> {}
+
+/**
+ * Factory function to create a console plugin for browser environments.
+ *
+ * @param config - Console plugin configuration
+ * @returns ConsolePlugin instance configured for browser
+ */
+export const createConsolePlugin: PluginFactory<ConsolePluginConfig, ConsolePlugin> = config => {
+  return new ConsolePlugin(config);
+};
+
+/**
+ * Factory function to create a console plugin for server environments.
+ *
+ * Creates a server-compatible console plugin that includes flush() capability.
+ *
+ * @param config - Console plugin configuration
+ * @returns ConsoleServerPlugin instance configured for server
+ */
+export const createConsoleServerPlugin: PluginFactory<
+  ConsolePluginConfig,
+  ConsoleServerPlugin
+> = config => {
+  return new ConsoleServerPlugin(config);
+};
+
+// Re-export types
+export type { ObservabilityPlugin, ObservabilityServerPlugin } from '../../core/plugin';