autotel 2.22.0 → 2.23.0

package/README.md

@@ -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)
@@ -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,17 +1565,119 @@ 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

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