vestig 0.11.4 → 0.13.0

package/README.md

@@ -27,6 +27,7 @@ A modern, runtime-agnostic structured logging library with automatic PII sanitiz
 | Runtime Agnostic | ✅ | ❌ | ❌ |
 | Auto PII Sanitization | ✅ | ❌ | ❌ |
 | GDPR/HIPAA/PCI-DSS Presets | ✅ | ❌ | ❌ |
+| Wide Events / Tail Sampling | ✅ | ❌ | ❌ |
 | Zero Config | ✅ | ✅ | ❌ |
 | TypeScript First | ✅ | ✅ | ⚠️ |
 | Edge Runtime Support | ✅ | ❌ | ❌ |
@@ -78,7 +79,7 @@ log.info('User login', {
 Send logs to multiple destinations simultaneously:
 
 ```typescript
-import { createLogger, ConsoleTransport, HTTPTransport, DatadogTransport } from 'vestig'
+import { createLogger, HTTPTransport, DatadogTransport, SentryTransport } from 'vestig'
 
 const log = createLogger()
 
@@ -97,10 +98,19 @@ log.addTransport(new DatadogTransport({
   tags: ['env:production'],
 }))
 
+// Add Sentry for error tracking
+log.addTransport(new SentryTransport({
+  name: 'sentry',
+  dsn: process.env.SENTRY_DSN,
+  environment: 'production',
+  release: 'my-app@1.0.0',
+  minLevel: 'warn', // Only send warn/error to Sentry
+}))
+
 // Initialize transports (starts flush timers)
 await log.init()
 
-// All logs go to console, HTTP endpoint, and Datadog
+// All logs go to console, HTTP endpoint, Datadog, and Sentry
 log.info('Server started', { port: 3000 })
 ```
 
@@ -112,6 +122,7 @@ log.info('Server started', { port: 3000 })
 | `HTTPTransport` | Send to any HTTP endpoint | Custom log aggregation |
 | `FileTransport` | Write to files with rotation | Server-side logging |
 | `DatadogTransport` | Datadog Log Management | Production observability |
+| `SentryTransport` | Sentry error tracking | Error monitoring, alerting |
 
 ### PII Sanitization with Presets
 
@@ -203,6 +214,58 @@ export async function GET(req: Request) {
 }
 ```
 
+### Wide Events (Canonical Log Lines)
+
+Wide Events capture **all context about a complete operation in ONE structured event**. Instead of scattered logs, you get a single comprehensive record per request.
+
+```typescript
+import { createLogger, createWideEvent } from 'vestig'
+
+const log = createLogger({
+  tailSampling: {
+    enabled: true,
+    alwaysKeepStatuses: ['error'],  // 100% of errors
+    slowThresholdMs: 2000,          // 100% of slow requests
+    successSampleRate: 0.1,         // 10% of successful requests
+    vipUserIds: ['user-123'],       // 100% for VIP users
+  }
+})
+
+// Create and enrich the wide event throughout the request
+const event = createWideEvent({ type: 'http.request' })
+
+// Add HTTP context
+event.merge('http', {
+  method: 'POST',
+  path: '/api/checkout',
+  status_code: 200,
+})
+
+// Add user context
+event.merge('user', {
+  id: 'user-456',
+  subscription: 'premium',
+})
+
+// Add performance metrics
+event.merge('performance', {
+  db_query_ms: 45,
+  external_api_ms: 230,
+})
+
+// End and emit the event
+const completedEvent = event.end({ status: 'success' })
+log.emitWideEvent(completedEvent)
+
+// Output: ONE event with 50+ fields, easily queryable
+```
+
+**Why Wide Events?**
+- **Debug faster**: All context in one place, no log correlation needed
+- **Reduce costs**: Tail sampling keeps 100% of errors, samples success
+- **Better queries**: "Show me slow requests from premium users with payment errors"
+- **No missing context**: You'll never again lose the request that caused an error
+
 ## Configuration
 
 ### Environment Variables
@@ -306,6 +369,36 @@ Generate correlation IDs (requestId, traceId, spanId).
 
 Create a sanitizer from a preset name.
 
+### `createWideEvent(config)`
+
+Create a wide event builder for accumulating context throughout a request.
+
+```typescript
+const event = createWideEvent({ type: 'http.request' })
+event.set('http', 'method', 'POST')
+event.merge('user', { id: 'user-123', tier: 'premium' })
+const completed = event.end({ status: 'success' })
+```
+
+### `log.emitWideEvent(event)`
+
+Emit a completed wide event through the logger's transports. Applies tail sampling if configured.
+
+### `createTailSampler(config)`
+
+Create a tail sampler for wide events. Used internally by `emitWideEvent()` but can be used standalone.
+
+```typescript
+const sampler = createTailSampler({
+  alwaysKeepStatuses: ['error'],
+  slowThresholdMs: 2000,
+  successSampleRate: 0.1,
+})
+if (sampler.shouldSample(event).sampled) {
+  log.emitWideEvent(event)
+}
+```
+
 ## Contributing
 
 We love contributions! Please read our [Contributing Guide](https://github.com/Arakiss/vestig/blob/main/CONTRIBUTING.md) to get started.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAwB,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEvF;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;CAKX,CAAA;AA4CV;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,CAavD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,CAAC,EAAE,YAAY,GAAG,oBAAoB,CAa3E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAwB,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEvF;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;CAKX,CAAA;AA4CV;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,CAevD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,CAAC,EAAE,YAAY,GAAG,oBAAoB,CAe3E"}

package/dist/config.js

@@ -61,6 +61,8 @@ export function getDefaultConfig() {
         context: getEnvContext(),
         namespace: '',
         sampling: undefined,
+        dedupe: undefined,
+        tailSampling: undefined,
     };
 }
 /**
@@ -77,6 +79,8 @@ export function mergeConfig(userConfig) {
         context: { ...defaults.context, ...userConfig?.context },
         namespace: userConfig?.namespace ?? defaults.namespace,
         sampling: userConfig?.sampling ?? defaults.sampling,
+        dedupe: userConfig?.dedupe ?? defaults.dedupe,
+        tailSampling: userConfig?.tailSampling ?? defaults.tailSampling,
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { VERSION } from './version';
-export { createLogger, LoggerImpl } from './logger';
-export type { Logger, LoggerConfig, ResolvedLoggerConfig, LogLevel, LogEntry, LogMetadata, LogContext, Transport, TransportConfig, BatchTransportConfig, HTTPTransportConfig, FileTransportConfig, DatadogTransportConfig, SerializedError, Runtime, FieldMatcher, SanitizePattern, SanitizeConfig, SanitizePreset, Span, SpanCallback, SpanEvent, SpanOptions, SpanStatus, SpanSyncCallback, Sampler, SamplerConfig, SamplingConfig, ProbabilitySamplerConfig, RateLimitSamplerConfig, NamespaceSamplerConfig, } from './types';
+export { createLogger, createLoggerAsync, initLogger, LoggerImpl } from './logger';
+export type { Logger, LoggerConfig, ResolvedLoggerConfig, LogLevel, LogEntry, LogMetadata, LogContext, Transport, TransportConfig, BatchTransportConfig, HTTPTransportConfig, FileTransportConfig, RotationInterval, DatadogTransportConfig, SentryTransportConfig, SerializedError, Runtime, FieldMatcher, SanitizePattern, SanitizeConfig, SanitizePreset, DedupeConfig, Span, SpanCallback, SpanEvent, SpanOptions, SpanStatus, SpanSyncCallback, Sampler, SamplerConfig, SamplingConfig, ProbabilitySamplerConfig, RateLimitSamplerConfig, NamespaceSamplerConfig, } from './types';
 export { RUNTIME, CAPABILITIES, IS_NODE, IS_BUN, IS_DENO, IS_EDGE, IS_BROWSER, IS_WORKER, IS_SERVER, } from './runtime';
 export type { RuntimeCapabilities } from './runtime';
 export { LOG_LEVELS, shouldLog, parseLogLevel } from './levels';
@@ -11,14 +11,21 @@ export { serializeError, isError, getErrorMessage } from './utils/error';
 export { Sanitizer, sanitize, createSanitizer, getPreset, mergeConfigs, COMMON_PATTERNS, PRESETS, } from './utils/sanitize';
 export { CircularBuffer } from './utils/buffer';
 export type { CircularBufferConfig } from './utils/buffer';
+export { Deduplicator } from './utils/dedupe';
+export type { DedupeResult } from './utils/dedupe';
 export { ConsoleTransport } from './transports/console';
 export type { ConsoleTransportConfig } from './transports/console';
 export { BatchTransport } from './transports/batch';
 export { HTTPTransport, HTTPTransportError } from './transports/http';
 export { FileTransport } from './transports/file';
 export { DatadogTransport, DatadogTransportError } from './transports/datadog';
+export { SentryTransport, SentryTransportError } from './transports/sentry';
 export { span, spanSync, startSpan, endSpan, getActiveSpan, withActiveSpan, SpanImpl, clearActiveSpans, getActiveSpanStackDepth, withSpanContext, withSpanContextAsync, } from './tracing';
 export { createSampler, createSamplerFromConfig, createProbabilitySampler, createRateLimitSampler, createNamespaceSampler, createCompositeSampler, } from './sampling';
+export { createWideEvent, WideEventBuilderImpl, getActiveWideEvent, withWideEvent, withWideEventAsync, } from './wide-events';
+export type { WideEvent, WideEventBuilder, WideEventConfig, WideEventContext, WideEventEndOptions, WideEventFields, WideEventStatus, TailSamplingConfig, } from './wide-events';
+export { MetricsCollector, globalMetrics, createMetricsCollector } from './metrics';
+export type { LoggerMetrics } from './metrics';
 /**
  * Default logger instance with auto-configuration
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,YAAY,EACX,MAAM,EACN,YAAY,EACZ,oBAAoB,EACpB,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,UAAU,EACV,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,OAAO,EAEP,YAAY,EACZ,eAAe,EACf,cAAc,EACd,cAAc,EAEd,IAAI,EACJ,YAAY,EACZ,SAAS,EACT,WAAW,EACX,UAAU,EACV,gBAAgB,EAEhB,OAAO,EACP,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,SAAS,CAAA;AAGhB,OAAO,EACN,OAAO,EACP,YAAY,EACZ,OAAO,EACP,MAAM,EACN,OAAO,EACP,OAAO,EACP,UAAU,EACV,SAAS,EACT,SAAS,GACT,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAGpD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAG/D,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGlE,OAAO,EACN,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EAEjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAGhD,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACxE,OAAO,EACN,SAAS,EACT,QAAQ,EACR,eAAe,EACf,SAAS,EACT,YAAY,EACZ,eAAe,EACf,OAAO,GACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAG9E,OAAO,EACN,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,OAAO,EACP,aAAa,EACb,cAAc,EACd,QAAQ,EAER,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACpB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACN,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,YAAY,CAAA;AAKnB;;GAEG;AACH,eAAO,MAAM,GAAG,0BAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,7 @@
 // Version
 export { VERSION } from './version';
 // Core exports
-export { createLogger, LoggerImpl } from './logger';
+export { createLogger, createLoggerAsync, initLogger, LoggerImpl } from './logger';
 // Runtime detection
 export { RUNTIME, CAPABILITIES, IS_NODE, IS_BUN, IS_DENO, IS_EDGE, IS_BROWSER, IS_WORKER, IS_SERVER, } from './runtime';
 // Log levels
@@ -16,18 +16,24 @@ parseTracestate, createTracestate, getTracestateValue, setTracestateValue, delet
 export { serializeError, isError, getErrorMessage } from './utils/error';
 export { Sanitizer, sanitize, createSanitizer, getPreset, mergeConfigs, COMMON_PATTERNS, PRESETS, } from './utils/sanitize';
 export { CircularBuffer } from './utils/buffer';
+export { Deduplicator } from './utils/dedupe';
 // Transports
 export { ConsoleTransport } from './transports/console';
 export { BatchTransport } from './transports/batch';
 export { HTTPTransport, HTTPTransportError } from './transports/http';
 export { FileTransport } from './transports/file';
 export { DatadogTransport, DatadogTransportError } from './transports/datadog';
+export { SentryTransport, SentryTransportError } from './transports/sentry';
 // Tracing - standalone functions and utilities
 export { span, spanSync, startSpan, endSpan, getActiveSpan, withActiveSpan, SpanImpl, 
 // Context utilities (for advanced use cases)
 clearActiveSpans, getActiveSpanStackDepth, withSpanContext, withSpanContextAsync, } from './tracing';
 // Sampling - factory functions for creating samplers
 export { createSampler, createSamplerFromConfig, createProbabilitySampler, createRateLimitSampler, createNamespaceSampler, createCompositeSampler, } from './sampling';
+// Wide Events - canonical log lines for comprehensive request context
+export { createWideEvent, WideEventBuilderImpl, getActiveWideEvent, withWideEvent, withWideEventAsync, } from './wide-events';
+// Metrics - Prometheus format export
+export { MetricsCollector, globalMetrics, createMetricsCollector } from './metrics';
 // Default logger instance (convenience)
 import { createLogger } from './logger';
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAsCnD,oBAAoB;AACpB,OAAO,EACN,OAAO,EACP,YAAY,EACZ,OAAO,EACP,MAAM,EACN,OAAO,EACP,OAAO,EACP,UAAU,EACV,SAAS,EACT,SAAS,GACT,MAAM,WAAW,CAAA;AAGlB,aAAa;AACb,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE/D,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAElE,qBAAqB;AACrB,OAAO,EACN,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB;AACjB,uCAAuC;AACvC,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,WAAW,CAAA;AAGlB,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACxE,OAAO,EACN,SAAS,EACT,QAAQ,EACR,eAAe,EACf,SAAS,EACT,YAAY,EACZ,eAAe,EACf,OAAO,GACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/C,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAE9E,+CAA+C;AAC/C,OAAO,EACN,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,OAAO,EACP,aAAa,EACb,cAAc,EACd,QAAQ;AACR,6CAA6C;AAC7C,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACpB,MAAM,WAAW,CAAA;AAElB,qDAAqD;AACrD,OAAO,EACN,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,YAAY,CAAA;AAEnB,wCAAwC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AA0ClF,oBAAoB;AACpB,OAAO,EACN,OAAO,EACP,YAAY,EACZ,OAAO,EACP,MAAM,EACN,OAAO,EACP,OAAO,EACP,UAAU,EACV,SAAS,EACT,SAAS,GACT,MAAM,WAAW,CAAA;AAGlB,aAAa;AACb,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE/D,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAElE,qBAAqB;AACrB,OAAO,EACN,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,iBAAiB;AACjB,uCAAuC;AACvC,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,WAAW,CAAA;AAGlB,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACxE,OAAO,EACN,SAAS,EACT,QAAQ,EACR,eAAe,EACf,SAAS,EACT,YAAY,EACZ,eAAe,EACf,OAAO,GACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC9E,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAE3E,+CAA+C;AAC/C,OAAO,EACN,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,OAAO,EACP,aAAa,EACb,cAAc,EACd,QAAQ;AACR,6CAA6C;AAC7C,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACpB,MAAM,WAAW,CAAA;AAElB,qDAAqD;AACrD,OAAO,EACN,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,YAAY,CAAA;AAEnB,sEAAsE;AACtE,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,GAClB,MAAM,eAAe,CAAA;AAYtB,qCAAqC;AACrC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAGnF,wCAAwC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAA"}

package/dist/logger.d.ts

@@ -10,6 +10,8 @@ export declare class LoggerImpl implements Logger {
     private children;
     private initialized;
     private sampler;
+    private deduplicator;
+    private tailSampler;
     constructor(config?: LoggerConfig);
     /**
      * Internal log method
@@ -33,6 +35,11 @@ export declare class LoggerImpl implements Logger {
      * Create a child logger with a namespace
      */
     child(namespace: string, config?: Partial<LoggerConfig>): Logger;
+    /**
+     * Internal method called by FinalizationRegistry to clean up stale entries
+     * @internal
+     */
+    cleanupChild(namespace: string): void;
     /**
      * Set the minimum log level
      */
@@ -120,9 +127,87 @@ export declare class LoggerImpl implements Logger {
      * ```
      */
     spanSync<T>(name: string, fn: SpanSyncCallback<T>, options?: SpanOptions): T;
+    /**
+     * Emit a completed wide event through the logger's transports.
+     *
+     * Wide events are comprehensive, single-event records of complete
+     * operations (like HTTP requests or background jobs).
+     *
+     * If tail sampling is configured, the event may be dropped based on:
+     * - Status (errors are always kept)
+     * - Duration (slow requests are always kept)
+     * - VIP users/tiers (always kept)
+     * - Random sampling for success events
+     *
+     * @param event - The completed WideEvent to emit
+     */
+    emitWideEvent(event: import('./wide-events/types').WideEvent): void;
+    /**
+     * Flatten wide event fields to dot-notation for LogEntry metadata.
+     */
+    private flattenFields;
 }
 /**
  * Create a new logger instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const logger = createLogger({ level: 'info' })
+ *
+ * // With namespace
+ * const dbLogger = createLogger({ namespace: 'db' })
+ *
+ * // For async initialization, see createLoggerAsync()
+ * ```
  */
 export declare function createLogger(config?: LoggerConfig): Logger;
+/**
+ * Create and initialize a logger instance asynchronously
+ *
+ * This function creates a logger and waits for all transports to initialize.
+ * Use this when you have transports that require async setup (file handles,
+ * database connections, HTTP clients with connection pooling, etc.).
+ *
+ * @param config - Logger configuration options
+ * @returns A promise that resolves to the initialized logger
+ *
+ * @example
+ * ```typescript
+ * // Initialize logger with async transports
+ * const logger = await createLoggerAsync({
+ *   level: 'info',
+ *   namespace: 'app'
+ * })
+ *
+ * // Add transports that need async init
+ * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+ * logger.addTransport(new HTTPTransport({ url: 'https://logs.example.com' }))
+ *
+ * // Or create with transports added first
+ * const logger = createLogger()
+ * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+ * const initializedLogger = await initLogger(logger)
+ * ```
+ */
+export declare function createLoggerAsync(config?: LoggerConfig): Promise<Logger>;
+/**
+ * Initialize an existing logger and its transports
+ *
+ * This is useful when you want to add transports first, then initialize them all.
+ *
+ * @param logger - The logger instance to initialize
+ * @returns A promise that resolves to the same logger after initialization
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'api' })
+ * logger.addTransport(new FileTransport({ path: './api.log' }))
+ * logger.addTransport(new DatadogTransport({ apiKey: process.env.DD_API_KEY }))
+ *
+ * // Initialize all transports
+ * await initLogger(logger)
+ * ```
+ */
+export declare function initLogger(logger: Logger): Promise<Logger>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAKA,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAGrB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAGX,QAAQ,EACR,WAAW,EACX,MAAM,EACN,YAAY,EAEZ,SAAS,EACT,MAAM,SAAS,CAAA;AAsDhB;;GAEG;AACH,qBAAa,UAAW,YAAW,MAAM;IACxC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAAkB;IACpC,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAA8C;IAC9D,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAuB;gBAE1B,MAAM,CAAC,EAAE,YAAY;IAiBjC;;OAEG;IACH,OAAO,CAAC,GAAG;IAuDX;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACpD,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACpD,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACnD,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK9B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACnD,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACpD,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/B;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM;IAgChE;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;OAEG;IACH,QAAQ,IAAI,QAAQ;IAIpB;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAgBxC;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAetC;;OAEG;IACH,aAAa,IAAI,SAAS,SAAS,EAAE;IAIrC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAKnF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC;CAI5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAE1D"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/logger.js

@@ -2,9 +2,10 @@ import { mergeConfig } from './config';
 import { getContext } from './context';
 import { LOG_LEVELS, shouldLog } from './levels';
 import { RUNTIME } from './runtime';
-import { createSampler } from './sampling';
+import { TailSampler, createSampler } from './sampling';
 import { span as spanFn, spanSync as spanSyncFn, } from './tracing';
 import { ConsoleTransport } from './transports/console';
+import { Deduplicator } from './utils/dedupe';
 import { isError, serializeError } from './utils/error';
 import { sanitize } from './utils/sanitize';
 /**
@@ -55,6 +56,16 @@ function formatArgs(args) {
     }
     return { message: String(first), metadata };
 }
+/**
+ * FinalizationRegistry for cleaning up stale WeakRef entries in children Map.
+ * When a child logger is garbage collected, this removes its entry from the parent's Map.
+ */
+const childLoggerRegistry = new FinalizationRegistry((heldValue) => {
+    const parent = heldValue.parent.deref();
+    if (parent) {
+        parent.cleanupChild(heldValue.namespace);
+    }
+});
 /**
  * Core logger implementation
  */
@@ -65,12 +76,22 @@ export class LoggerImpl {
     children = new Map();
     initialized = false;
     sampler = null;
+    deduplicator = null;
+    tailSampler = null;
     constructor(config) {
         this.config = mergeConfig(config);
         // Initialize sampler if configured
         if (this.config.sampling) {
             this.sampler = createSampler(this.config.sampling);
         }
+        // Initialize deduplicator if configured
+        if (this.config.dedupe?.enabled) {
+            this.deduplicator = new Deduplicator(this.config.dedupe);
+        }
+        // Initialize tail sampler for wide events if configured
+        if (this.config.tailSampling?.enabled !== false && this.config.tailSampling) {
+            this.tailSampler = new TailSampler(this.config.tailSampling);
+        }
         // Add default console transport
         this.transports.push(new ConsoleTransport({
             structured: this.config.structured,
@@ -89,8 +110,9 @@ export class LoggerImpl {
         // Get context from async storage
         const asyncContext = getContext();
         // Sanitize metadata if enabled
+        // Note: sanitize() can return null/undefined for edge cases, so we fallback to empty object
         const sanitizedMetadata = this.config.sanitize
-            ? sanitize(metadata, this.config.sanitizeFields)
+            ? (sanitize(metadata, this.config.sanitizeFields) ?? {})
             : metadata;
         // Build log entry
         const entry = {
@@ -112,6 +134,34 @@ export class LoggerImpl {
         if (this.sampler && !this.sampler.shouldSample(entry)) {
             return;
         }
+        // Apply deduplication if configured
+        if (this.deduplicator) {
+            const dedupeResult = this.deduplicator.shouldSuppress(message, level, this.config.namespace);
+            if (dedupeResult.suppressed) {
+                return;
+            }
+            // If this is a flush after suppression, emit summary first
+            if (dedupeResult.isFlush && dedupeResult.suppressedCount) {
+                const summaryEntry = {
+                    timestamp: new Date().toISOString(),
+                    level,
+                    message: `[dedupe] Previous message repeated ${dedupeResult.suppressedCount} time${dedupeResult.suppressedCount > 1 ? 's' : ''}`,
+                    metadata: { originalMessage: message },
+                    runtime: RUNTIME,
+                    namespace: this.config.namespace || undefined,
+                };
+                // Send summary to transports
+                for (const transport of this.transports) {
+                    if (transport.config.enabled === false)
+                        continue;
+                    if (transport.config.level && !shouldLog(level, transport.config.level))
+                        continue;
+                    if (transport.config.filter && !transport.config.filter(summaryEntry))
+                        continue;
+                    transport.log(summaryEntry);
+                }
+            }
+        }
         // Send to all enabled transports
         for (const transport of this.transports) {
             // Check if transport is enabled
@@ -180,9 +230,21 @@ export class LoggerImpl {
         // Cache if no custom config (using WeakRef to allow GC)
         if (!config) {
             this.children.set(fullNamespace, new WeakRef(child));
+            // Register for automatic cleanup when child is garbage collected
+            childLoggerRegistry.register(child, {
+                parent: new WeakRef(this),
+                namespace: fullNamespace,
+            });
         }
         return child;
     }
+    /**
+     * Internal method called by FinalizationRegistry to clean up stale entries
+     * @internal
+     */
+    cleanupChild(namespace) {
+        this.children.delete(namespace);
+    }
     /**
      * Set the minimum log level
      */
@@ -270,6 +332,11 @@ export class LoggerImpl {
      * Destroy all transports (call on shutdown)
      */
     async destroy() {
+        // Clean up deduplicator
+        if (this.deduplicator) {
+            this.deduplicator.destroy();
+            this.deduplicator = null;
+        }
         await Promise.all(this.transports.map((t) => t.destroy?.()));
         this.transports = [];
         this.initialized = false;
@@ -323,11 +390,151 @@ export class LoggerImpl {
         const fullName = this.config.namespace ? `${this.config.namespace}:${name}` : name;
         return spanSyncFn(fullName, fn, options);
     }
+    /**
+     * Emit a completed wide event through the logger's transports.
+     *
+     * Wide events are comprehensive, single-event records of complete
+     * operations (like HTTP requests or background jobs).
+     *
+     * If tail sampling is configured, the event may be dropped based on:
+     * - Status (errors are always kept)
+     * - Duration (slow requests are always kept)
+     * - VIP users/tiers (always kept)
+     * - Random sampling for success events
+     *
+     * @param event - The completed WideEvent to emit
+     */
+    emitWideEvent(event) {
+        // Check if logging is enabled
+        if (!this.config.enabled) {
+            return;
+        }
+        // Apply tail sampling if configured
+        if (this.tailSampler) {
+            const result = this.tailSampler.shouldSample(event);
+            if (!result.sampled) {
+                // Event was dropped by tail sampling
+                return;
+            }
+        }
+        // Convert WideEvent to LogEntry
+        const entry = {
+            timestamp: event.ended_at,
+            level: event.level,
+            message: `[wide-event] ${event.event_type}`,
+            metadata: {
+                event_type: event.event_type,
+                status: event.status,
+                started_at: event.started_at,
+                duration_ms: event.duration_ms,
+                ...this.flattenFields(event.fields),
+            },
+            context: event.context,
+            runtime: event.runtime,
+            namespace: this.config.namespace || undefined,
+            error: event.error,
+        };
+        // Sanitize metadata if enabled
+        if (this.config.sanitize && entry.metadata) {
+            entry.metadata = sanitize(entry.metadata, this.config.sanitizeFields) ?? {};
+        }
+        // Send to all enabled transports (no regular sampling/dedupe for wide events)
+        for (const transport of this.transports) {
+            if (transport.config.enabled === false)
+                continue;
+            if (transport.config.level && !shouldLog(entry.level, transport.config.level))
+                continue;
+            if (transport.config.filter && !transport.config.filter(entry))
+                continue;
+            transport.log(entry);
+        }
+    }
+    /**
+     * Flatten wide event fields to dot-notation for LogEntry metadata.
+     */
+    flattenFields(fields) {
+        const result = {};
+        for (const [category, categoryFields] of Object.entries(fields)) {
+            for (const [key, value] of Object.entries(categoryFields)) {
+                result[`${category}.${key}`] = value;
+            }
+        }
+        return result;
+    }
 }
 /**
  * Create a new logger instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const logger = createLogger({ level: 'info' })
+ *
+ * // With namespace
+ * const dbLogger = createLogger({ namespace: 'db' })
+ *
+ * // For async initialization, see createLoggerAsync()
+ * ```
  */
 export function createLogger(config) {
     return new LoggerImpl(config);
 }
+/**
+ * Create and initialize a logger instance asynchronously
+ *
+ * This function creates a logger and waits for all transports to initialize.
+ * Use this when you have transports that require async setup (file handles,
+ * database connections, HTTP clients with connection pooling, etc.).
+ *
+ * @param config - Logger configuration options
+ * @returns A promise that resolves to the initialized logger
+ *
+ * @example
+ * ```typescript
+ * // Initialize logger with async transports
+ * const logger = await createLoggerAsync({
+ *   level: 'info',
+ *   namespace: 'app'
+ * })
+ *
+ * // Add transports that need async init
+ * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+ * logger.addTransport(new HTTPTransport({ url: 'https://logs.example.com' }))
+ *
+ * // Or create with transports added first
+ * const logger = createLogger()
+ * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+ * const initializedLogger = await initLogger(logger)
+ * ```
+ */
+export async function createLoggerAsync(config) {
+    const logger = new LoggerImpl(config);
+    await logger.init();
+    return logger;
+}
+/**
+ * Initialize an existing logger and its transports
+ *
+ * This is useful when you want to add transports first, then initialize them all.
+ *
+ * @param logger - The logger instance to initialize
+ * @returns A promise that resolves to the same logger after initialization
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'api' })
+ * logger.addTransport(new FileTransport({ path: './api.log' }))
+ * logger.addTransport(new DatadogTransport({ apiKey: process.env.DD_API_KEY }))
+ *
+ * // Initialize all transports
+ * await initLogger(logger)
+ * ```
+ */
+export async function initLogger(logger) {
+    // The Logger interface doesn't expose init(), so we cast to access it
+    // This is safe because createLogger always returns a LoggerImpl
+    const impl = logger;
+    await impl.init();
+    return logger;
+}
 //# sourceMappingURL=logger.js.map