@od-oneapp/observability 2026.2.2001-canary.1 → 2026.2.2899-canary

package/README.md

@@ -1,523 +1,100 @@
-# @repo/observability
+# @od-oneapp/observability
 
-A comprehensive, type-safe observability package for the OneApp monorepo. Provides unified logging, error tracking,
-performance monitoring, and tracing across client, server, and edge environments with support for multiple providers
-(Sentry, BetterStack, Console).
+Centralized observability manager for OneApp.
 
-## Quick Reference
+## Current Model (Sentry-first)
 
-- **Can build:** NO (TypeScript library, no build step required)
-- **Version:** 2025.11.1201
-- **License:** MIT
+- `console` is built-in
+- `sentry` is loaded dynamically from `@od-oneapp/integration-sentry`
+- Non-Sentry providers are not auto-loaded
+- BetterStack exports are deprecated compatibility shims
 
-### Exports
-
-**Core:**
-
-- `.` - Shared utilities and types
-- `./client` - Browser (non-Next.js)
-- `./server` - Node.js server
-- `./client/next` - Next.js client components
-- `./server/next` - Next.js server components
-- `./server/edge` - Edge runtime
-- `./env` - Environment configuration
-
-**Plugins:**
-
-- `./plugins/console` - Console logging plugin
-- `./plugins/sentry` - Sentry error tracking
-- `./plugins/betterstack` - BetterStack logging
-- `./plugins/logtape` - LogTape integration
-- `./plugins/sentry-microfrontend` - Micro-frontend Sentry
-
-**Environment Configs:** Each plugin exports `./plugins/{name}/env`
-
-### AI Usage Hints
-
-```typescript
-// ✅ CORRECT: Logging (Canonical)
-import { logInfo, logError } from "@od-oneapp/shared/logger";
-
-// ✅ CORRECT: Observability initialization (Next.js Server Component)
-import { observability } from "@repo/observability/server/next";
-
-// ✅ CORRECT: Observability initialization (Next.js Client Component)
-import { getObservability } from "@repo/observability/client/next";
-
-// ✅ CORRECT: Edge Runtime (Middleware, Edge API Routes)
-import { observability } from "@repo/observability/server/edge";
-```
-
-## Features
-
-- 🔌 **Plugin-Based**: Extensible architecture supporting multiple providers
-- 🌐 **Multi-Environment**: Client, server, Next.js, edge runtime support
-- 📊 **Performance Monitoring**: Web Vitals, custom metrics, distributed tracing
-- 🛡️ **Type-Safe**: Full TypeScript with strict type checking
-- 🔄 **Graceful Degradation**: Continues operation if providers fail
-- 🎯 **Error Tracking**: Structured error reporting with breadcrumbs
-- 🚀 **Zero-Config**: Auto-detection based on environment variables
-- 🔐 **Security-First**: Input validation and sanitization
-
-## Installation
-
-Already included in the monorepo. Add to your workspace:
+## Install
 
 ```bash
-pnpm add @repo/observability
-```
-
-## Quick Start
-
-### Next.js Client Component
-
-```tsx
-"use client";
-
-import { logInfo, logError } from "@od-oneapp/shared/logger";
-
-export function UserProfile() {
-  const handleClick = async () => {
-    try {
-      logInfo("User profile viewed", { userId: "123" });
-      // Your logic here
-    } catch (error) {
-      logError(error as Error, { component: "UserProfile" });
-    }
-  };
-
-  return <button onClick={handleClick}>View Profile</button>;
-}
-```
-
-### Next.js Server Component
-
-```tsx
-import { getObservability } from "@repo/observability/server-next";
-import { logInfo, logError } from "@od-oneapp/shared/logger";
-
-export default async function ServerPage() {
-  const observability = await getObservability();
-  logInfo("Server page rendered", { page: "/dashboard" });
-
-  try {
-    const data = await fetchData();
-    return <div>{data}</div>;
-  } catch (error) {
-    logError(error as Error);
-    observability.captureException(error as Error);
-    throw error;
-  }
-}
-```
-
-### API Route
-
-```typescript
-import { getObservability } from "@repo/observability/server-next";
-import { logInfo, logError } from "@od-oneapp/shared/logger";
-import { NextRequest, NextResponse } from "next/server";
-
-export async function POST(request: NextRequest) {
-  const observability = await getObservability();
-
-  try {
-    const body = await request.json();
-
-    observability.setUser({ id: body.userId, email: body.email });
-    logInfo("API request", { endpoint: "/api/users" });
-
-    const result = await processRequest(body);
-    return NextResponse.json({ success: true, data: result });
-  } catch (error) {
-    logError(error as Error, { endpoint: "/api/users" });
-    observability.captureException(error as Error, { endpoint: "/api/users" });
-    return NextResponse.json({ error: "Internal error" }, { status: 500 });
-  }
-}
-```
-
-## Environment Variables
-
-### Core Configuration
-
-```bash
-NODE_ENV=development | production
-NEXT_PUBLIC_OBSERVABILITY_DEBUG=true
-NEXT_PUBLIC_OBSERVABILITY_CONSOLE_ENABLED=true
-```
-
-### Sentry
-
-```bash
-SENTRY_DSN=https://key@sentry.io/project
-NEXT_PUBLIC_SENTRY_DSN=https://key@sentry.io/project # Client-side
-SENTRY_ENVIRONMENT=production
-SENTRY_RELEASE=v1.0.0
-SENTRY_ORG=your-org
-SENTRY_PROJECT=your-project
-SENTRY_TRACES_SAMPLE_RATE=0.1
-SENTRY_PROFILES_SAMPLE_RATE=0.1
-SENTRY_REPLAYS_SESSION_SAMPLE_RATE=0.1
-SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1.0
-```
-
-### BetterStack (Logtail)
-
-```bash
-BETTER_STACK_SOURCE_TOKEN=your-token
-NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN=your-token # Client-side
-BETTER_STACK_INGESTING_URL=https://in.logs.betterstack.com
-BETTERSTACK_STATUS_PAGE_ID=your-page-id
-LOGTAIL_SOURCE_TOKEN=your-token # Legacy name
-```
-
-## Usage Examples
-
-### Basic Logging
-
-```typescript
-import { logDebug, logInfo, logWarn, logError } from "@od-oneapp/shared/logger";
-
-logDebug("Processing request", { requestId: "123" });
-logInfo("User logged in", { userId: "user-456" });
-logWarn("Rate limit approaching", { currentRate: 95 });
-logError("Failed to save data", { operation: "db.save" });
-```
-
-### Exception Tracking
-
-```typescript
-try {
-  await riskyOperation();
-} catch (error) {
-  observability.captureException(error, {
-    extra: { userId: user.id, operation: "checkout" },
-    tags: { environment: "production", feature: "checkout" }
-  });
-  throw error;
-}
-```
-
-### User Context
-
-```typescript
-// Set user context (attached to all future events)
-observability.setUser({
-  id: "user-123",
-  email: "john@example.com",
-  username: "johndoe"
-});
-
-// Clear user context (e.g., on logout)
-observability.setUser(null);
-```
-
-### Breadcrumbs
-
-```typescript
-// Track user journey
-observability.addBreadcrumb({
-  message: "User clicked checkout",
-  category: "user-action",
-  level: "info",
-  data: { cartTotal: 99.99 }
-});
-
-// When error occurs, breadcrumbs provide context
-observability.captureException(new Error("Payment failed"));
-```
-
-### Performance Monitoring (Sentry)
-
-```typescript
-import { observability, SentryPlugin } from "@repo/observability/server-next";
-
-const sentry = observability.getPlugin<SentryPlugin>("sentry");
-
-if (sentry) {
-  const transaction = sentry.startTransaction({
-    name: "Process Order",
-    op: "http.server"
-  });
-
-  try {
-    const span = sentry.startSpan({ name: "Validate Cart", op: "validation" });
-    await validateCart(cart);
-    span?.finish();
-
-    transaction?.finish();
-  } catch (error) {
-    transaction?.finish();
-    throw error;
-  }
-}
-```
-
-### Web Vitals (Client-Side)
-
-```tsx
-"use client";
-
-import { getObservability, SentryPlugin } from "@repo/observability/client-next";
-
-export function WebVitalsReporter() {
-  useEffect(() => {
-    const reportWebVitals = async (metric: any) => {
-      const obs = await getObservability();
-      const sentry = obs.getPlugin<SentryPlugin>("sentry");
-
-      if (sentry) {
-        sentry.recordWebVital(metric.name, metric.value, {
-          rating: metric.rating,
-          unit: "millisecond"
-        });
-      }
-    };
-
-    import("web-vitals").then(({ onCLS, onFID, onFCP, onLCP, onTTFB }) => {
-      onCLS(reportWebVitals);
-      onFID(reportWebVitals);
-      onFCP(reportWebVitals);
-      onLCP(reportWebVitals);
-      onTTFB(reportWebVitals);
-    });
-  }, []);
-
-  return null;
-}
-```
-
-## Provider Plugins
-
-### Sentry
-
-Error tracking, performance monitoring, session replay.
-
-```typescript
-import { createSentryPlugin } from "@repo/observability/plugins/sentry";
-
-const sentry = createSentryPlugin({
-  dsn: process.env.SENTRY_DSN,
-  environment: process.env.NODE_ENV,
-  tracesSampleRate: 1.0,
-  replaysSessionSampleRate: 0.1
-});
+pnpm add @od-oneapp/observability @od-oneapp/integration-sentry @sentry/nextjs
 ```
 
-### BetterStack
+## Next.js Runtime Usage
 
-Structured logging and log aggregation.
+### Client
 
-```typescript
-import { createBetterStackPlugin } from "@repo/observability/plugins/betterstack";
+```ts
+import { createClientObservability } from '@od-oneapp/observability/client/next';
 
-const betterstack = createBetterStackPlugin({
-  sourceToken: process.env.BETTER_STACK_SOURCE_TOKEN,
-  batchInterval: 1000,
-  batchSize: 100
+const obs = await createClientObservability({
+  providers: {
+    sentry: {
+      enabled: true,
+      options: {
+        dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+      },
+    },
+  },
 });
 ```
 
-### Console
-
-Development logging to console.
+### Server
 
-```typescript
-import { createConsolePlugin } from "@repo/observability/plugins/console";
+```ts
+import { createServerObservability } from '@od-oneapp/observability/server/next';
 
-const console = createConsolePlugin({
-  prefix: "[MyApp]",
-  enabled: process.env.NODE_ENV === "development"
+const obs = await createServerObservability({
+  providers: {
+    sentry: {
+      enabled: true,
+      options: {
+        dsn: process.env.SENTRY_DSN,
+      },
+    },
+  },
 });
 ```
 
-### Sentry MicroFrontend
-
-Specialized for micro-frontend architectures.
+### Edge
 
-```typescript
-import { createSentryMicroFrontendPlugin } from "@repo/observability/plugins/sentry-microfrontend";
+```ts
+import { createEdgeObservability } from '@od-oneapp/observability/server/edge';
 
-const sentry = createSentryMicroFrontendPlugin({
-  isHost: true,
-  backstageApp: "my-app",
-  backstageApps: {
-    "my-app": "https://app-dsn@sentry.io/123"
+const obs = await createEdgeObservability({
+  providers: {
+    sentry: { enabled: true },
   },
-  globalTags: { team: "platform", version: "1.0.0" }
 });
 ```
 
-## Advanced Usage
-
-### Multi-Provider Setup
-
-```typescript
-import { ObservabilityBuilder } from "@repo/observability/factory/builder";
-import { createSentryPlugin } from "@repo/observability/plugins/sentry";
-import { createBetterStackPlugin } from "@repo/observability/plugins/betterstack";
-
-const observability = ObservabilityBuilder.create()
-  .withPlugin(createSentryPlugin({ dsn: process.env.SENTRY_DSN }))
-  .withPlugin(createBetterStackPlugin({ sourceToken: process.env.LOGTAIL_TOKEN }))
-  .withLifecycle({
-    onError: (error, plugin) => console.error(`${plugin.name} error:`, error),
-    onInitialized: (plugin) => console.log(`${plugin.name} initialized`)
-  })
-  .build();
-```
-
-### Custom Plugin
-
-```typescript
-import { ObservabilityPlugin } from "@repo/observability";
-
-class CustomPlugin implements ObservabilityPlugin {
-  name = "custom";
-  enabled = true;
-
-  getClient() {
-    return undefined;
-  }
-  async initialize() {
-    /* Setup */
-  }
-  async shutdown() {
-    /* Cleanup */
-  }
-
-  captureException(error: Error | unknown, context?: any) {
-    // Your implementation
-  }
-
-  captureMessage(message: string, level = "info", context?: any) {
-    // Your implementation
-  }
-
-  setUser(user: any) {
-    /* Your implementation */
-  }
-  addBreadcrumb(breadcrumb: any) {
-    /* Your implementation */
-  }
-  withScope(callback: any) {
-    callback({});
-  }
-}
-```
-
-## API Reference
-
-### ObservabilityManager
-
-- `addPlugin(plugin)` - Add plugin
-- `getPlugin<T>(name)` - Get plugin by name
-- `initialize()` - Initialize all plugins
-- `shutdown()` - Shutdown all plugins
-- `captureException(error, context?)` - Capture exception
-- `captureMessage(message, level?, context?)` - Capture message
-- `setUser(user)` - Set user context
-- `addBreadcrumb(breadcrumb)` - Add breadcrumb
-- `withScope(callback)` - Scoped context
-- `flush(timeout?)` - Flush pending events
-
-### Logging (Canonical)
-
-Logging is now handled by the `@od-oneapp/shared/logger` package.
-
-- `logDebug(message, context?)` - Debug logging
-- `logInfo(message, context?)` - Info logging
-- `logWarn(message, context?)` - Warning logging
-- `logError(message, context?)` - Error logging
-
-### ObservabilityBuilder
-
-- `create()` - New builder instance
-- `withPlugin(plugin)` - Add single plugin
-- `withPlugins(plugins)` - Add multiple plugins
-- `withLifecycle(lifecycle)` - Set lifecycle hooks
-- `withAutoInitialize(enabled)` - Configure auto-init
-- `build()` - Build manager
-- `buildWithAutoInit()` - Build and initialize
-
-## Testing
-
-```bash
-pnpm test          # Run tests
-pnpm test:coverage # With coverage
-pnpm typecheck     # Type checking
-pnpm lint          # Lint code
-```
-
-## Troubleshooting
-
-### Plugins not initializing
-
-```typescript
-if (observability.hasInitializationError()) {
-  console.error("Init failed:", observability.getInitializationError());
-}
-console.log("Enabled:", observability.getEnabledPluginNames());
-```
-
-### Events not in Sentry
-
-Check DSN, sampling rates, and debug mode:
-
-```bash
-SENTRY_DEBUG=true
-```
-
-### "Accessed server variable on client"
-
-Use `NEXT_PUBLIC_` prefix for client-side variables:
-
-```bash
-NEXT_PUBLIC_SENTRY_DSN=https://key@sentry.io/project
-```
-
-## Best Practices
-
-1. Use environment-specific exports
-2. Set user context after authentication
-3. Add breadcrumbs for error context
-4. Use structured context objects
-5. Sample performance data in production
-6. Flush before process termination
-7. Never log sensitive data (passwords, tokens, PII)
-
-## Security
-
-- ✅ User data automatically validated and sanitized
-- ✅ Field length limits prevent DoS
-- ✅ Unknown fields stripped for security
-- ✅ Environment variables type-checked
-- ⚠️ Use `beforeSend` hooks to scrub sensitive info
-
-## Documentation
+## DSN Auto-Detection
 
-For comprehensive documentation, see:
+If you omit provider config, Sentry is auto-loaded when either env var is present:
+- `SENTRY_DSN`
+- `NEXT_PUBLIC_SENTRY_DSN`
 
-- **[Observability Package Overview](../apps/docs/packages/observability/overview.mdx)**
-- **Architecture**: See "Architecture" section above
-- **API Reference**: See "API Reference" section above
+## Provider Config Types
 
-## License
+- `ObservabilityProviderName = 'console' | 'sentry'`
+- `ObservabilityProvidersConfig`
+- `NextObservabilityOptions`
+- `MissingProviderPackageError`
 
-MIT
+If Sentry is configured but the integration package is missing, runtime throws `MissingProviderPackageError` with install guidance.
 
-## Support
+## Sentry Integration Package
 
-Open an issue in the monorepo or contact the platform team.
+Use `@od-oneapp/integration-sentry/config` for Next.js SDK configuration (`Sentry.init` and `withSentryConfig`).
 
-## 📚 Comprehensive Documentation
+It supports deterministic first-class layering:
+- `runtime.common`
+- `runtime.server`
+- `runtime.edge`
+- `runtime.client`
+- `build`
 
-For detailed documentation, see:
+Escape hatches are available as:
+- `rawServer`
+- `rawEdge`
+- `rawClient`
+- `rawBuild`
 
-- **[Audit Reports](../../apps/docs/content/docs/audits/observability/)** - Comprehensive audits, fixes, and security
-  reviews
-- **[Technical Guides](../../apps/docs/content/docs/packages/observability/)** - Implementation guides and best
-  practices
+## BetterStack Deprecation
 
-All comprehensive documentation has been centralized in the docs app.
+`@od-oneapp/observability/plugins/betterstack` remains temporarily for backward compatibility, but it is a no-op shim and should be removed from app code.

package/client-next.d.mts

@@ -1,20 +1,19 @@
-import { a as Breadcrumb, c as ObservabilityConfig, d as ObservabilityServer, f as ObservabilityUser, l as ObservabilityContext, o as LogLevel, s as ObservabilityClient, u as ObservabilityScope } from "./plugin-pvH_kv0a.mjs";
-import { t as ObservabilityManager } from "./manager-CONEYB97.mjs";
-import { n as ObservabilityBuilder, t as createObservability } from "./index-CktVJJqJ.mjs";
-import { n as BetterStackPluginConfig, t as BetterStackPlugin } from "./plugin-CEOGIJFN.mjs";
+import { a as Breadcrumb, c as ObservabilityClient, d as ObservabilityProviderConfig, f as ObservabilityProviderName, g as ObservabilityUser, h as ObservabilityServer, l as ObservabilityConfig, m as ObservabilityScope, o as LogLevel, p as ObservabilityProvidersConfig, s as NextObservabilityOptions, u as ObservabilityContext } from "./plugin-CD6OSG7J.mjs";
+import { t as ObservabilityManager } from "./manager-GGdKqdV2.mjs";
+import { n as ObservabilityBuilder, t as createObservability } from "./index-BBs_2frZ.mjs";
+import { t as MissingProviderPackageError } from "./load-provider-mEuA8Tkf.mjs";
 import { Env } from "./plugins-betterstack-env.mjs";
+import { BetterStackPlugin, BetterStackPluginConfig } from "./plugins-betterstack.mjs";
 import { ConsolePlugin, ConsolePluginConfig } from "./plugins-console.mjs";
-import { n as SentryPluginConfig, t as SentryPlugin } from "./plugin-81171XQL.mjs";
-import { Env as Env$1 } from "./plugins-sentry-env.mjs";
-import "./plugins-sentry.mjs";
-import { c as MicroFrontendMode, i as SentryMicroFrontendPlugin, l as SentryMicroFrontendConfig, s as BackstageAppConfig } from "./utils-6Gg4fkvH.mjs";
+import { Env as Env$1, SentryPlugin, SentryPluginConfig } from "./plugins-sentry.mjs";
+import { c as MicroFrontendMode, i as SentryMicroFrontendPlugin, l as SentryMicroFrontendConfig, s as BackstageAppConfig } from "./utils-cqicHWHw.mjs";
 import "./plugins-sentry-microfrontend.mjs";
 
 //#region src/client-next.d.ts
-declare function createClientObservability(): Promise<ObservabilityManager>;
+declare function createClientObservability(options?: NextObservabilityOptions): Promise<ObservabilityManager>;
 declare function getObservability(): Promise<ObservabilityManager>;
 declare const configureLogger: () => void;
 type LogContext = Record<string, any>;
 //#endregion
-export { type BackstageAppConfig, type Env as BetterStackEnv, BetterStackPlugin, type BetterStackPluginConfig, Breadcrumb, ConsolePlugin, type ConsolePluginConfig, LogContext, LogLevel, type MicroFrontendMode, ObservabilityBuilder, ObservabilityClient, ObservabilityConfig, ObservabilityContext, ObservabilityScope, ObservabilityServer, ObservabilityUser, type Env$1 as SentryEnv, type SentryMicroFrontendConfig, SentryMicroFrontendPlugin, SentryPlugin, type SentryPluginConfig, configureLogger, createClientObservability, createObservability, getObservability };
+export { type BackstageAppConfig, type Env as BetterStackEnv, BetterStackPlugin, type BetterStackPluginConfig, Breadcrumb, ConsolePlugin, type ConsolePluginConfig, LogContext, LogLevel, type MicroFrontendMode, MissingProviderPackageError, NextObservabilityOptions, ObservabilityBuilder, ObservabilityClient, ObservabilityConfig, ObservabilityContext, ObservabilityProviderConfig, ObservabilityProviderName, ObservabilityProvidersConfig, ObservabilityScope, ObservabilityServer, ObservabilityUser, type Env$1 as SentryEnv, type SentryMicroFrontendConfig, SentryMicroFrontendPlugin, SentryPlugin, type SentryPluginConfig, configureLogger, createClientObservability, createObservability, getObservability };
 //# sourceMappingURL=client-next.d.mts.map

package/client-next.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"client-next.d.mts","names":[],"sources":["../src/client-next.ts"],"mappings":";;;;;;;;;;;;;iBAoBsB,yBAAA,CAAA,GAAyB,OAAA,CAAA,oBAAA;AAAA,iBAoDzB,gBAAA,CAAA,GAAoB,OAAA,CAAQ,oBAAA;AAAA,cAqDrC,eAAA;AAAA,KAKD,UAAA,GAAa,MAAA"}
+{"version":3,"file":"client-next.d.mts","names":[],"sources":["../src/client-next.ts"],"mappings":";;;;;;;;;;;;iBA6DsB,yBAAA,CACpB,OAAA,GAAU,wBAAA,GACT,OAAA,CAAQ,oBAAA;AAAA,iBAgDW,gBAAA,CAAA,GAAoB,OAAA,CAAQ,oBAAA;AAAA,cAsDrC,eAAA;AAAA,KAKD,UAAA,GAAa,MAAA"}