autotel 2.21.0 → 2.23.0

package/README.md

@@ -6,10 +6,10 @@
 
 **Write once, observe everywhere.** Instrument your Node.js code a single time, keep the DX you love, and stream traces, metrics, logs, and product events to **any** observability stack without vendor lock-in.
 
-- **Drop-in DX** – one `init()` and ergonomic helpers like `trace()`, `span()`, `withTracing()`, decorators, and batch instrumentation.
-- **Platform freedom** – OTLP-first design plus subscribers for PostHog, Mixpanel, Amplitude, and anything else via custom exporters/readers.
-- **Production hardening** – adaptive sampling (10% baseline, 100% errors/slow paths), rate limiting, circuit breakers, payload validation, and automatic sensitive-field redaction.
-- **Auto enrichment** – service metadata, deployment info, and AsyncLocalStorage-powered correlation IDs automatically flow into spans, metrics, logs, and events.
+- **Drop-in DX** : one `init()` and ergonomic helpers like `trace()`, `span()`, `withTracing()`, decorators, and batch instrumentation.
+- **Platform freedom** : OTLP-first design plus subscribers for PostHog, Mixpanel, Amplitude, and anything else via custom exporters/readers.
+- **Production hardening** : adaptive sampling (10% baseline, 100% errors/slow paths), rate limiting, circuit breakers, payload validation, and automatic sensitive-field redaction.
+- **Auto enrichment** : service metadata, deployment info, and AsyncLocalStorage-powered correlation IDs automatically flow into spans, metrics, logs, and events.
 
 > Raw OpenTelemetry is verbose, and vendor SDKs create lock-in. Autotel gives you the best parts of both: clean ergonomics **and** total ownership of your telemetry.
 
@@ -76,6 +76,9 @@ Replace `NODE_OPTIONS` and 30+ lines of SDK boilerplate with `init()`, wrap func
     - [What You Get](#what-you-get)
     - [Query Examples](#query-examples)
     - [Configuration Options](#configuration-options)
+    - [Request Logger DX](#request-logger-dx)
+    - [Drain Pipeline (Batch + Retry + Flush)](#drain-pipeline-batch--retry--flush)
+    - [parseError (Frontend/API Consumers)](#parseerror-frontendapi-consumers)
   - [Auto Instrumentation \& Advanced Configuration](#auto-instrumentation--advanced-configuration)
     - [⚠️ autoInstrumentations vs. Manual Instrumentations](#️-autoinstrumentations-vs-manual-instrumentations)
       - [Option A: Auto-instrumentations only (all defaults)](#option-a-auto-instrumentations-only-all-defaults)
@@ -358,8 +361,8 @@ function timed<T>(operation: string, fn: () => Promise<T>): Promise<T> {
 
 **Two patterns supported:**
 
-1. **Factory pattern** `trace(ctx => (...args) => result)` – Returns a wrapped function for reuse
-2. **Immediate execution** `trace(ctx => result)` – Executes once immediately, returns the result directly
+1. **Factory pattern** `trace(ctx => (...args) => result)` : Returns a wrapped function for reuse
+2. **Immediate execution** `trace(ctx => result)` : Executes once immediately, returns the result directly
 
 - Automatic span lifecycle (`start`, `end`, status, and error recording).
 - Function names feed `operation.name`, `code.function`, and events enrichment.
@@ -530,8 +533,8 @@ app.use((req, res, next) => {
 
 ### Reusable Middleware Helpers
 
-- `withTracing(options)` – create a preconfigured wrapper (service name, default attributes, skip rules).
-- `instrument(object, options)` – batch-wrap entire modules while skipping helpers or private functions.
+- `withTracing(options)` : create a preconfigured wrapper (service name, default attributes, skip rules).
+- `instrument(object, options)` : batch-wrap entire modules while skipping helpers or private functions.
 
 ```typescript
 import { withTracing, instrument } from 'autotel';
@@ -1504,7 +1507,7 @@ export const processCheckout = trace((ctx) => async (order: Order) => {
 
 When a span ends, a canonical log line is automatically emitted with:
 
-- **Core fields**: `operation`, `traceId`, `spanId`, `correlationId`, `duration_ms`, `status_code`
+- **Core fields**: `operation`, `traceId`, `spanId`, `correlationId`, `duration_ms`, `duration`, `status_code`
 - **ALL span attributes**: Every attribute you set with `ctx.setAttribute()`
 - **Resource attributes**: `service.name`, `service.version`, `deployment.environment`
 - **Timestamp**: ISO 8601 format
@@ -1520,6 +1523,7 @@ When a span ends, a canonical log line is automatically emitted with:
   "spanId": "00f067aa0ba902b7",
   "correlationId": "4bf92f3577b34da",
   "duration_ms": 124.7,
+  "duration": "125ms",
   "status_code": 1,
   "user.id": "user-123",
   "user.subscription": "premium",
@@ -1561,27 +1565,129 @@ init({
   service: 'my-app',
   canonicalLogLines: {
     enabled: true,
-    rootSpansOnly: true, // Only log root spans (one per request)
-    minLevel: 'info', // Minimum log level ('debug' | 'info' | 'warn' | 'error')
-    logger: pino(), // Custom logger (defaults to OTel Logs API)
+    rootSpansOnly: true,
+    minLevel: 'info',
+    logger: pino(),
+    pretty: true, // tree-formatted console output (defaults to NODE_ENV=development)
+    keep: [{ status: 500 }, { durationMs: 1000 }], // declarative tail sampling
+    shouldEmit: ({ event }) => {
+      // or use a custom predicate (overrides keep)
+      const isError = Number(event.status_code) === 2;
+      const isSlow = Number(event.duration_ms ?? 0) >= 1000;
+      return isError || isSlow || Math.random() < 0.1;
+    },
+    drain: async ({ event }) => {
+      await fetch('https://logs.example.com/ingest', {
+        method: 'POST',
+        body: JSON.stringify(event),
+      });
+    },
     messageFormat: (span) => {
-      // Custom message format
       const status = span.status.code === 2 ? 'ERROR' : 'SUCCESS';
       return `${span.name} [${status}]`;
     },
-    includeResourceAttributes: true, // Include service.name, service.version, etc.
+    includeResourceAttributes: true,
+  },
+});
+```
+
+### Request Logger DX
+
+For teams that prefer `log.set({...})` ergonomics, you can use `getRequestLogger()`.
+It writes directly to span attributes/events, so canonical log lines still emit one
+wide event per request.
+
+```typescript
+import { trace, getRequestLogger, createStructuredError } from 'autotel';
+
+export const checkout = trace((ctx) => async (order: Order) => {
+  const log = getRequestLogger(ctx);
+
+  log.set({ user: { id: order.userId, plan: order.plan } });
+  log.set({
+    cart: { total_cents: order.totalCents, item_count: order.items.length },
+  });
+
+  try {
+    await processPayment(order);
+  } catch (cause) {
+    log.error(
+      createStructuredError({
+        message: 'Payment failed',
+        why: 'Card declined by issuer',
+        fix: 'Try another payment method',
+        link: 'https://docs.example.com/errors/payment-declined',
+        cause,
+      }),
+      { step: 'payment' },
+    );
+    throw cause;
+  }
+});
+```
+
+You also get:
+
+- `log.getContext()` to inspect the accumulated request context.
+- `log.emitNow(overrides?)` to capture an immediate snapshot (adds a span event
+  and returns `{ timestamp, traceId, spanId, correlationId, context }`).
+
+### Drain Pipeline (Batch + Retry + Flush)
+
+If you want batching/retry behavior for canonical drains, wrap `drain`
+with `createDrainPipeline()` style logging:
+
+```typescript
+import { createDrainPipeline, init } from 'autotel';
+
+const pipeline = createDrainPipeline({
+  batch: { size: 50, intervalMs: 2000 },
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+  maxBufferSize: 1000,
+});
+
+const drain = pipeline(async (batch) => {
+  await fetch('https://logs.example.com/ingest', {
+    method: 'POST',
+    body: JSON.stringify(batch.map((ctx) => ctx.event)),
+  });
+});
+
+init({
+  service: 'my-app',
+  canonicalLogLines: {
+    enabled: true,
+    rootSpansOnly: true,
+    drain,
   },
 });
+
+await drain.flush();
+```
+
+### parseError (Frontend/API Consumers)
+
+Use `parseError()` to normalize unknown caught errors into a stable shape:
+
+```typescript
+import { parseError } from 'autotel';
+
+try {
+  await api.checkout(order);
+} catch (error) {
+  const parsed = parseError(error);
+  showError(parsed.message, parsed.why, parsed.fix);
+}
 ```
 
 ## Auto Instrumentation & Advanced Configuration
 
-- `autoInstrumentations` – Enable OpenTelemetry auto-instrumentations (HTTP, Express, Fastify, Prisma, Pino…). Requires `@opentelemetry/auto-instrumentations-node`.
-- `instrumentations` – Provide manual instrumentation instances, e.g., `new HttpInstrumentation()`.
-- `resource` / `resourceAttributes` – Declare cluster/region/tenant metadata once and it flows everywhere.
-- `spanProcessor`, `metricReader`, `logRecordProcessors` – Plug in any OpenTelemetry exporter or your in-house pipeline.
-- `headers` – Attach vendor auth headers when using the built-in OTLP HTTP exporters.
-- `sdkFactory` – Receive the Autotel defaults and return a fully customized `NodeSDK` for the rare cases you need complete control.
+- `autoInstrumentations` : Enable OpenTelemetry auto-instrumentations (HTTP, Express, Fastify, Prisma, Pino…). Requires `@opentelemetry/auto-instrumentations-node`.
+- `instrumentations` : Provide manual instrumentation instances, e.g., `new HttpInstrumentation()`.
+- `resource` / `resourceAttributes` : Declare cluster/region/tenant metadata once and it flows everywhere.
+- `spanProcessor`, `metricReader`, `logRecordProcessors` : Plug in any OpenTelemetry exporter or your in-house pipeline.
+- `headers` : Attach vendor auth headers when using the built-in OTLP HTTP exporters.
+- `sdkFactory` : Receive the Autotel defaults and return a fully customized `NodeSDK` for the rare cases you need complete control.
 
 ```typescript
 import { init } from 'autotel';
@@ -1721,12 +1827,12 @@ NODE_OPTIONS="--experimental-loader=@opentelemetry/instrumentation/hook.mjs --im
 
 ## Operational Safety & Runtime Controls
 
-- **Adaptive sampling** – 10% baseline, 100% for errors/slow spans by default (override via `sampler`).
-- **Rate limiting & circuit breakers** – Prevent telemetry storms when backends misbehave.
-- **Validation** – Configurable attribute/event name lengths, maximum counts, and nesting depth.
-- **Sensitive data redaction** – Passwords, tokens, API keys, and any custom regex you provide are automatically masked before export.
-- **Auto-flush** – Events buffers drain when root spans end (disable with `flushOnRootSpanEnd: false`).
-- **Runtime flags** – Toggle metrics or swap endpoints via env vars without code edits.
+- **Adaptive sampling** : 10% baseline, 100% for errors/slow spans by default (override via `sampler`).
+- **Rate limiting & circuit breakers** : Prevent telemetry storms when backends misbehave.
+- **Validation** : Configurable attribute/event name lengths, maximum counts, and nesting depth.
+- **Sensitive data redaction** : Passwords, tokens, API keys, and any custom regex you provide are automatically masked before export.
+- **Auto-flush** : Events buffers drain when root spans end (disable with `flushOnRootSpanEnd: false`).
+- **Runtime flags** : Toggle metrics or swap endpoints via env vars without code edits.
 
 ```bash
 # Disable metrics without touching code (metrics are ON by default)
@@ -2231,17 +2337,17 @@ The `autotel-edge` package is optimized for edge runtimes with automatic flush b
 
 ## API Reference
 
-- `init(config)` – Bootstraps the SDK (call once).
-- `trace(fn | name, fn)` – Wraps functions with spans and optional context access.
-- `span(options, fn)` – Creates nested spans for ad-hoc blocks.
-- `withTracing(options)` – Produces reusable wrappers with shared configuration.
-- `instrument(target, options)` – Batch-wraps an object of functions.
-- `Trace` decorator – Adds tracing to class methods (TypeScript 5+).
-- `instrumentDatabase(db, options)` – Adds automatic DB spans (Drizzle, etc.).
-- `Metric` class & helpers (`createHistogram`, etc.) – Emit OpenTelemetry metrics.
-- `Event` class & `track()` helper – Send product events/funnels/outcomes/values via subscribers.
-- `Logger` interface – Bring your own Pino/Winston logger; autotel auto-instruments it for trace context and OTLP export.
-- `PostHogSubscriber`, `MixpanelSubscriber`, … – Provided in `autotel-subscribers`; create your own by implementing the `EventSubscriber` interface.
+- `init(config)` : Bootstraps the SDK (call once).
+- `trace(fn | name, fn)` : Wraps functions with spans and optional context access.
+- `span(options, fn)` : Creates nested spans for ad-hoc blocks.
+- `withTracing(options)` : Produces reusable wrappers with shared configuration.
+- `instrument(target, options)` : Batch-wraps an object of functions.
+- `Trace` decorator : Adds tracing to class methods (TypeScript 5+).
+- `instrumentDatabase(db, options)` : Adds automatic DB spans (Drizzle, etc.).
+- `Metric` class & helpers (`createHistogram`, etc.) : Emit OpenTelemetry metrics.
+- `Event` class & `track()` helper : Send product events/funnels/outcomes/values via subscribers.
+- `Logger` interface : Bring your own Pino/Winston logger; autotel auto-instruments it for trace context and OTLP export.
+- `PostHogSubscriber`, `MixpanelSubscriber`, … : Provided in `autotel-subscribers`; create your own by implementing the `EventSubscriber` interface.
 
 Each API is type-safe, works in both ESM and CJS, and is designed to minimize boilerplate while staying close to OpenTelemetry primitives.
 

package/dist/auto.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkQKUGUDXJ_cjs = require('./chunk-QKUGUDXJ.cjs');
+var chunkHSEIUH7F_cjs = require('./chunk-HSEIUH7F.cjs');
 var chunk6YIDHH2S_cjs = require('./chunk-6YIDHH2S.cjs');
 require('./chunk-GVLK7YUU.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
 require('./chunk-ELW34S4C.cjs');
 require('./chunk-CU6IDACR.cjs');
-require('./chunk-ONK2Y22L.cjs');
+require('./chunk-6S5RUKU3.cjs');
 require('./chunk-YS6C2YJE.cjs');
 require('./chunk-BGVKKL2N.cjs');
 require('./chunk-AZ24DJAG.cjs');
@@ -23,7 +23,7 @@ module$1.register("import-in-the-middle/hook.mjs", (typeof document === 'undefin
 var yamlConfig = chunk6YIDHH2S_cjs.loadYamlConfig();
 var autoInstrumentationsEnv = process.env.AUTOTEL_INTEGRATIONS;
 var autoInstrumentations = autoInstrumentationsEnv === "true" ? true : autoInstrumentationsEnv ? autoInstrumentationsEnv.split(",").map((s) => s.trim()) : yamlConfig?.autoInstrumentations ?? ["http", "express"];
-chunkQKUGUDXJ_cjs.init({
+chunkHSEIUH7F_cjs.init({
   service: yamlConfig?.service ?? process.env.OTEL_SERVICE_NAME ?? "unknown-service",
   debug: yamlConfig?.debug ?? process.env.AUTOTEL_DEBUG === "true",
   autoInstrumentations

package/dist/auto.js

@@ -1,11 +1,11 @@
-import { init } from './chunk-BS757SL2.js';
+import { init } from './chunk-724XLWR3.js';
 import { loadYamlConfig } from './chunk-YTGF4L2C.js';
 import './chunk-X4RMFFMR.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
 import './chunk-SNINLBEE.js';
 import './chunk-6UQRVUN3.js';
-import './chunk-2RQDNGV3.js';
+import './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';
 import './chunk-XND7WBVX.js';
 import './chunk-B33XPEKY.js';

package/dist/{chunk-EWH2542B.js → chunk-3AMR5XLZ.js}

@@ -1,4 +1,4 @@
-import { trace } from './chunk-GZFH6P5U.js';
+import { trace } from './chunk-GY4CRZSV.js';
 import { extractLinksFromBatch, createLinkFromHeaders } from './chunk-XND7WBVX.js';
 import { SpanKind, propagation, context } from '@opentelemetry/api';
 
@@ -790,5 +790,5 @@ function clearOrderingState() {
 }
 
 export { clearOrderingState, traceConsumer, traceProducer };
-//# sourceMappingURL=chunk-EWH2542B.js.map
-//# sourceMappingURL=chunk-EWH2542B.js.map
+//# sourceMappingURL=chunk-3AMR5XLZ.js.map
+//# sourceMappingURL=chunk-3AMR5XLZ.js.map