@od-oneapp/observability 2026.1.1301

package/src/factory/index.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Factory functions for creating observability instances
+ * Factory functions for creating observability instances
+ */
+
+import { ObservabilityManager } from '../core/manager';
+
+import { ObservabilityBuilder } from './builder';
+
+import type { ObservabilityPlugin, ObservabilityServerPlugin } from '../core/plugin';
+
+export { ObservabilityManager } from '../core/manager';
+export { ObservabilityBuilder } from './builder';
+
+/**
+ * Create an observability instance with the provided plugins.
+ *
+ * Factory function that creates a configured ObservabilityManager with the given plugins.
+ * Provides a simpler API than using ObservabilityBuilder directly.
+ *
+ * @param plugins - Array of observability plugins to include
+ * @param options - Optional configuration options
+ * @param options.autoInitialize - Whether to auto-initialize plugins (default: true)
+ * @returns Configured ObservabilityManager instance
+ *
+ * @example
+ * ```typescript
+ * const obs = createObservability([
+ *   createConsolePlugin(),
+ *   createSentryPlugin({ dsn: '...' }),
+ * ], { autoInitialize: true });
+ * ```
+ */
+export function createObservability(
+  plugins: (ObservabilityPlugin | ObservabilityServerPlugin)[],
+  options?: {
+    autoInitialize?: boolean;
+  },
+): ObservabilityManager {
+  const builder = new ObservabilityBuilder();
+
+  if (options?.autoInitialize !== undefined) {
+    builder.withAutoInitialize(options.autoInitialize);
+  }
+
+  return builder.withPlugins(plugins).build();
+}
+
+/**
+ * Create a no-op observability instance for testing or when observability is disabled.
+ *
+ * Returns an ObservabilityManager with no plugins configured. All observability methods
+ * will be no-ops. Useful for testing or when observability should be disabled.
+ *
+ * Note: For logging, use @repo/shared/logger instead.
+ *
+ * @returns Empty ObservabilityManager instance
+ *
+ * @example
+ * ```typescript
+ * const obs = createNoOpObservability();
+ * obs.captureMessage('This will not be logged'); // No-op
+ * ```
+ */
+export function createNoOpObservability(): ObservabilityManager {
+  return new ObservabilityManager();
+}

package/src/factory/presets.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Common observability configurations and presets
+ * Common observability configurations and presets
+ */
+
+import { env } from '../../env';
+import { createBetterStackPlugin } from '../plugins/betterstack';
+import { env as betterStackEnv } from '../plugins/betterstack/env';
+import { createConsolePlugin } from '../plugins/console';
+import { createSentryPlugin } from '../plugins/sentry';
+import { env as sentryEnv } from '../plugins/sentry/env';
+
+import { ObservabilityBuilder } from './builder';
+
+/**
+ * Create development preset observability configuration.
+ *
+ * Configures observability for development environments with console logging enabled.
+ * Automatically detects development mode and adds appropriate plugins.
+ *
+ * @returns ObservabilityBuilder configured for development
+ */
+export async function createDevelopmentObservability(): Promise<ObservabilityBuilder> {
+  const builder = ObservabilityBuilder.create();
+
+  // Always add console in development
+  if (env.NEXT_PUBLIC_NODE_ENV === 'development') {
+    builder.withPlugin(createConsolePlugin());
+  }
+
+  return builder;
+}
+
+/**
+ * Create production preset observability configuration.
+ *
+ * Configures observability for production environments with error tracking (Sentry)
+ * and logging (Better Stack) if configured. Only adds plugins when credentials are available.
+ *
+ * @returns ObservabilityBuilder configured for production
+ */
+export async function createProductionObservability(): Promise<ObservabilityBuilder> {
+  const builder = ObservabilityBuilder.create();
+
+  // Add Sentry if DSN is configured
+  if (sentryEnv.SENTRY_DSN || sentryEnv.NEXT_PUBLIC_SENTRY_DSN) {
+    builder.withPlugin(createSentryPlugin());
+  }
+
+  // Add Better Stack if token is configured
+  const hasToken =
+    betterStackEnv.BETTER_STACK_SOURCE_TOKEN ??
+    betterStackEnv.BETTERSTACK_SOURCE_TOKEN ??
+    betterStackEnv.LOGTAIL_SOURCE_TOKEN;
+
+  if (hasToken) {
+    builder.withPlugin(createBetterStackPlugin());
+  }
+
+  return builder;
+}
+
+/**
+ * Create observability configuration based on environment.
+ *
+ * Automatically selects the appropriate preset (development or production) based on
+ * the NODE_ENV environment variable. Provides a convenient way to get environment-appropriate
+ * observability configuration.
+ *
+ * @returns ObservabilityBuilder configured for the current environment
+ */
+export async function createAutoConfiguredObservability(): Promise<ObservabilityBuilder> {
+  if (env.NEXT_PUBLIC_NODE_ENV === 'production') {
+    return createProductionObservability();
+  } else {
+    return createDevelopmentObservability();
+  }
+}

package/src/hooks/useObservability.ts

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview React hooks for observability integration
+ * React hooks for observability integration
+ * Optimized for React 19 features including use() hook and automatic error boundaries
+ */
+
+'use client';
+
+import { use, useEffect, useSyncExternalStore } from 'react';
+
+import { logDebug, logError } from '@repo/shared/logs';
+
+import type { ObservabilityManager } from '../core/manager';
+
+/**
+ * Global observability instance promise for React 19's use() hook
+ * This allows components to suspend while waiting for initialization
+ */
+let observabilityPromise: Promise<ObservabilityManager> | null = null;
+
+/**
+ * Set the observability promise for React 19 Suspense integration
+ * @param promise - Promise that resolves to ObservabilityManager
+ */
+export function setObservabilityPromise(promise: Promise<ObservabilityManager>): void {
+  observabilityPromise = promise;
+}
+
+/**
+ * React 19+ hook that suspends until observability is ready
+ * Uses the new use() hook for automatic Suspense integration
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { Suspense } from 'react';
+ * import { useObservability } from '@repo/observability/hooks/useObservability';
+ * import { logInfo } from '@repo/shared/logs';
+ *
+ * function MyComponent() {
+ *   const observability = useObservability();
+ *
+ *   useEffect(() => {
+ *     logInfo('Component mounted');
+ *   }, [observability]);
+ *
+ *   return <div>Hello</div>;
+ * }
+ *
+ * export default function Page() {
+ *   return (
+ *     <Suspense fallback={<div>Loading...</div>}>
+ *       <MyComponent />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+export function useObservability(): ObservabilityManager {
+  if (!observabilityPromise) {
+    throw new Error(
+      'Observability promise not set. Call setObservabilityPromise() during module initialization.',
+    );
+  }
+
+  // React 19's use() hook automatically suspends until promise resolves
+  return use(observabilityPromise);
+}
+
+// Module-level state for legacy hook (fixes state recreation bug)
+let legacyCurrentInstance: ObservabilityManager | undefined = undefined;
+const legacyListeners = new Set<() => void>();
+let legacyInitialized = false;
+
+/**
+ * Legacy hook for React 18 compatibility
+ * Returns observability instance once available, undefined during initialization
+ * Does not use Suspense
+ *
+ * @deprecated Use useObservability() with Suspense for React 19+
+ */
+export function useObservabilityLegacy(): ObservabilityManager | undefined {
+  const subscribe = (callback: () => void) => {
+    legacyListeners.add(callback);
+
+    // If promise exists and instance not yet resolved, wait for it
+    if (observabilityPromise && !legacyInitialized) {
+      legacyInitialized = true;
+      void (async () => {
+        try {
+          const instance = await observabilityPromise;
+          legacyCurrentInstance = instance;
+          legacyListeners.forEach(listener => {
+            listener();
+          });
+        } catch {
+          legacyInitialized = false; // Allow retry on failure
+        }
+      })();
+    }
+
+    return () => {
+      legacyListeners.delete(callback);
+    };
+  };
+
+  const getSnapshot = (): ObservabilityManager | undefined => {
+    return legacyCurrentInstance;
+  };
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+/**
+ * Hook to track component lifecycle events
+ * Automatically logs mount, update, and unmount events
+ *
+ * @param componentName - Name of the component for logging
+ * @param deps - Dependencies to track for updates
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { useObservabilityLifecycle } from '@repo/observability/hooks/useObservability';
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   useObservabilityLifecycle('UserProfile', [userId]);
+ *
+ *   return <div>User {userId}</div>;
+ * }
+ * ```
+ */
+export function useObservabilityLifecycle(
+  componentName: string,
+  deps: readonly unknown[] = [],
+): void {
+  useEffect(() => {
+    // Log mount
+    logDebug(`Component mounted: ${componentName}`, {
+      component: componentName,
+      event: 'mount',
+    });
+
+    // Log unmount
+    return () => {
+      logDebug(`Component unmounted: ${componentName}`, {
+        component: componentName,
+        event: 'unmount',
+      });
+    };
+  }, deps);
+}
+
+/**
+ * Hook to automatically report errors to observability
+ * Compatible with React 19 error boundaries
+ *
+ * @param error - Error to report
+ * @param errorInfo - Additional error information
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { useObservabilityError } from '@repo/observability/hooks/useObservability';
+ *
+ * function MyComponent() {
+ *   const [error, setError] = useState<Error | null>(null);
+ *
+ *   useObservabilityError(error, { component: 'MyComponent' });
+ *
+ *   if (error) {
+ *     return <div>Error occurred</div>;
+ *   }
+ *
+ *   return <div>Hello</div>;
+ * }
+ * ```
+ */
+export function useObservabilityError(
+  error: Error | null | undefined,
+  errorInfo?: Record<string, unknown>,
+): void {
+  useEffect(() => {
+    if (error && observabilityPromise) {
+      void (async () => {
+        try {
+          const obs = await observabilityPromise;
+          obs.captureException(error, {
+            extra: errorInfo,
+            tags: {
+              source: 'react-component',
+            },
+          });
+        } catch (reportError) {
+          logError('Failed to report error to observability', {
+            error: reportError,
+            originalError: error,
+          });
+        }
+      })();
+    }
+  }, [error, errorInfo]);
+}

package/src/plugins/betterstack/env.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Better Stack (Logtail) environment configuration
+ * Better Stack (Logtail) environment configuration
+ * Updated to support official @logtail packages
+ */
+
+import { logWarn } from '@repo/shared/logger';
+import { createEnv } from '@t3-oss/env-core';
+import { z } from 'zod/v4';
+
+// Create validated env object
+export const env = createEnv({
+  server: {
+    // Legacy support
+    LOGTAIL_SOURCE_TOKEN: z.string().optional(),
+    BETTERSTACK_SOURCE_TOKEN: z.string().optional(),
+
+    // Official Better Stack environment variables
+    BETTER_STACK_SOURCE_TOKEN: z.string().optional(),
+    BETTER_STACK_INGESTING_URL: z.string().url().optional(),
+    BETTER_STACK_LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error', 'off']).optional(),
+  },
+  client: {
+    // Legacy support
+    NEXT_PUBLIC_LOGTAIL_TOKEN: z.string().optional(),
+    NEXT_PUBLIC_BETTERSTACK_TOKEN: z.string().optional(),
+
+    // Official Better Stack client environment variables
+    NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN: z.string().optional(),
+    NEXT_PUBLIC_BETTER_STACK_INGESTING_URL: z.string().url().optional(),
+    NEXT_PUBLIC_BETTER_STACK_LOG_LEVEL: z
+      .enum(['debug', 'info', 'warn', 'error', 'off'])
+      .optional(),
+  },
+  clientPrefix: 'NEXT_PUBLIC_',
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+  onInvalidAccess: (variable: string) => {
+    throw new Error(
+      `❌ Attempted to access a server-side environment variable on the client: ${variable}`,
+    );
+  },
+  onValidationError: error => {
+    logWarn('Better Stack environment validation failed', { error });
+    // Don't throw in packages - use fallbacks
+    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 with proper
+ * priority handling for legacy and official Better Stack variable names.
+ *
+ * @returns Environment object with Better Stack configuration values
+ */
+export function safeEnv() {
+  if (env) return env;
+
+  // Fallback values for resilience with proper priority
+  return {
+    // Legacy support
+    LOGTAIL_SOURCE_TOKEN:
+      process.env.LOGTAIL_SOURCE_TOKEN ?? process.env.BETTERSTACK_SOURCE_TOKEN ?? '',
+    BETTERSTACK_SOURCE_TOKEN:
+      process.env.BETTERSTACK_SOURCE_TOKEN ?? process.env.LOGTAIL_SOURCE_TOKEN ?? '',
+    NEXT_PUBLIC_LOGTAIL_TOKEN:
+      process.env.NEXT_PUBLIC_LOGTAIL_TOKEN ?? process.env.NEXT_PUBLIC_BETTERSTACK_TOKEN ?? '',
+    NEXT_PUBLIC_BETTERSTACK_TOKEN:
+      process.env.NEXT_PUBLIC_BETTERSTACK_TOKEN ?? process.env.NEXT_PUBLIC_LOGTAIL_TOKEN ?? '',
+
+    // Official Better Stack (preferred)
+    BETTER_STACK_SOURCE_TOKEN:
+      process.env.BETTER_STACK_SOURCE_TOKEN ??
+      process.env.LOGTAIL_SOURCE_TOKEN ??
+      process.env.BETTERSTACK_SOURCE_TOKEN ??
+      '',
+    BETTER_STACK_INGESTING_URL: process.env.BETTER_STACK_INGESTING_URL ?? '',
+    BETTER_STACK_LOG_LEVEL:
+      (process.env.BETTER_STACK_LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error' | 'off') ?? 'info',
+    NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN:
+      process.env.NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN ??
+      process.env.NEXT_PUBLIC_LOGTAIL_TOKEN ??
+      process.env.NEXT_PUBLIC_BETTERSTACK_TOKEN ??
+      '',
+    NEXT_PUBLIC_BETTER_STACK_INGESTING_URL:
+      process.env.NEXT_PUBLIC_BETTER_STACK_INGESTING_URL ?? '',
+    NEXT_PUBLIC_BETTER_STACK_LOG_LEVEL:
+      (process.env.NEXT_PUBLIC_BETTER_STACK_LOG_LEVEL as
+        | 'debug'
+        | 'info'
+        | 'warn'
+        | 'error'
+        | 'off') ?? 'info',
+  };
+}
+
+// Export type
+export type Env = typeof env;

package/src/plugins/betterstack/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Better Stack (Logtail) plugin exports
+ * Better Stack (Logtail) plugin exports
+ */
+
+// Export plugin and factory
+export { BetterStackPlugin, createBetterStackPlugin } from './plugin';
+export type { BetterStackPluginConfig } from './plugin';
+
+// Re-export Better Stack environment configuration
+export { env, safeEnv } from './env';
+export type { Env } from './env';
+
+// Export types
+export type { ObservabilityPlugin, ObservabilityServerPlugin } from '../../core/plugin';