@contrail/telemetry 2.0.0-dev-telemetry-own-otel-1 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-04-06
+
+### Added
+
+- **Request context on every log** — `logger` is now context-aware. During a request, all logs (including from library code like `@contrail/dynamodb` or `@contrail/auth`) automatically include `user.id`, `org.slug`, `url.path`, and other request fields. No import changes needed.
+- **`withLogContext(fields, fn)`** — Wrap any block of code with extra log context. Context stacks on top of any existing request context and is removed when the callback exits.
+- **`addStream(streamEntry)`** — Hook a custom pino stream into the logger to tap into all log records (e.g. collect logs in memory for a UI panel).
+- **`flushLogs()`** — Flush pending logs to the OTLP collector before a Lambda execution environment freezes.
+- **OTel log export** — Logs are sent to an OTLP HTTP endpoint (when `OTEL_EXPORTER_OTLP_ENDPOINT` is set) with Lambda attributes, span context, and flattened structured fields.
+- **Structured stdout** — CloudWatch-friendly tab-delimited format with `pino-pretty` support in local dev.
+
+### Breaking Changes
+
+- **`logger` is now a Proxy, not a raw Pino instance.** Behavior is identical when no request context is active (falls back to the base logger). This only matters if you were comparing `logger === baseLogger` — they are no longer the same reference. Use `baseLogger` if you need the raw Pino instance.
+
 ## [1.0.2] - 2026-03-25
 
 ### Added

package/lib/logger/index.d.ts

@@ -2,8 +2,9 @@ import pino from 'pino';
 export { parseOtelResourceAttributes } from './parse-otel-resource-attributes';
 export { PINO_LEVEL_TO_OTEL_SEVERITY, PINO_LEVEL_TO_NAME } from './logger-config';
 export { ATTR_LOG_MESSAGE, ATTR_LOG_PAYLOAD } from './semantic-conventions';
+export { loggerStorage, withLogContext } from './log-context';
 export declare const baseLogger: pino.Logger<never, boolean>;
-export declare const logger: pino.Logger<never, boolean>;
+export declare const logger: pino.Logger;
 /**
  * Add a stream destination to the logger's multistream.
  * Use this to wire additional log sinks (e.g. InMemoryLogStream in app-framework).

package/lib/logger/index.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 var _a, _b, _c, _d, _e, _f, _g;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = exports.baseLogger = exports.ATTR_LOG_PAYLOAD = exports.ATTR_LOG_MESSAGE = exports.PINO_LEVEL_TO_NAME = exports.PINO_LEVEL_TO_OTEL_SEVERITY = exports.parseOtelResourceAttributes = void 0;
+exports.logger = exports.baseLogger = exports.withLogContext = exports.loggerStorage = exports.ATTR_LOG_PAYLOAD = exports.ATTR_LOG_MESSAGE = exports.PINO_LEVEL_TO_NAME = exports.PINO_LEVEL_TO_OTEL_SEVERITY = exports.parseOtelResourceAttributes = void 0;
 exports.addStream = addStream;
 exports.flushLogs = flushLogs;
 const pino_1 = __importDefault(require("pino"));
@@ -29,6 +29,9 @@ Object.defineProperty(exports, "PINO_LEVEL_TO_NAME", { enumerable: true, get: fu
 var semantic_conventions_3 = require("./semantic-conventions");
 Object.defineProperty(exports, "ATTR_LOG_MESSAGE", { enumerable: true, get: function () { return semantic_conventions_3.ATTR_LOG_MESSAGE; } });
 Object.defineProperty(exports, "ATTR_LOG_PAYLOAD", { enumerable: true, get: function () { return semantic_conventions_3.ATTR_LOG_PAYLOAD; } });
+var log_context_1 = require("./log-context");
+Object.defineProperty(exports, "loggerStorage", { enumerable: true, get: function () { return log_context_1.loggerStorage; } });
+Object.defineProperty(exports, "withLogContext", { enumerable: true, get: function () { return log_context_1.withLogContext; } });
 // --- Environment & Resource Setup ---
 const semantic_conventions_4 = require("../semantic-conventions");
 const LAMBDA_ENV_OTEL_ATTRIBUTES = getLambdaEnvAttributes();
@@ -230,7 +233,8 @@ exports.baseLogger = (0, pino_1.default)({
         [semantic_conventions_1.ATTR_SERVICE_VERSION]: serviceVersion,
     },
 }, pino_1.default.multistream(buildPinoStreams()));
-exports.logger = exports.baseLogger;
+const log_context_2 = require("./log-context");
+exports.logger = (0, log_context_2.createContextAwareLogger)(exports.baseLogger);
 // --- Public API ---
 /**
  * Add a stream destination to the logger's multistream.
@@ -257,10 +261,12 @@ async function flushLogs(options) {
         ]);
     }
     catch (error) {
-        console.error('[OTel Log Flush Failed]', JSON.stringify({
+        // Write directly to stderr to avoid routing through pino → OTel during an OTel failure
+        // (same pattern as setGlobalErrorHandler above).
+        process.stderr.write(`[OTel Log Flush Failed] ${JSON.stringify({
             error: error instanceof Error ? error.message : String(error),
             timeoutMs,
             timestamp: new Date().toISOString(),
-        }));
+        })}\n`);
     }
 }

package/lib/logger/log-context.d.ts

@@ -0,0 +1,61 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Logger } from 'pino';
+/**
+ * Stores the current request-scoped child logger per async context.
+ * Used by `createContextAwareLogger` to make the `logger` export context-aware,
+ * and by `withLogContext` to set context for a block of code.
+ */
+export declare const loggerStorage: AsyncLocalStorage<Logger>;
+/**
+ * Wraps a base Pino logger in a Proxy that is aware of AsyncLocalStorage context.
+ * Called once at module init — the returned Proxy becomes the `logger` export.
+ *
+ * When code calls `logger.info(...)`, the Proxy intercepts the property access:
+ * 1. Checks `loggerStorage.getStore()` for a request-scoped child logger
+ * 2. If found, delegates to the child (which has user/org/request fields baked in)
+ * 3. If not found (e.g. during startup), falls back to the base logger
+ *
+ * This means all 39+ library files that `import { logger } from '@contrail/telemetry'`
+ * automatically get request-scoped context without any import changes.
+ *
+ * @example
+ * // In telemetry/src/logger/index.ts (called once):
+ * export const logger = createContextAwareLogger(baseLogger);
+ *
+ * // In any library file:
+ * import { logger } from '@contrail/telemetry';
+ * logger.info('query executed'); // includes user.id, org.slug, etc. during a request
+ *
+ * ## How Proxy and Reflect work
+ *
+ * **Proxy** — wraps an object and intercepts operations (get, set, has, etc.).
+ * We only intercept `get` so that property reads (like `.info`, `.warn`, `.level`)
+ * are redirected to the context-appropriate logger.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
+ *
+ * **Reflect.get(target, prop, receiver)** — performs the default property read.
+ * Using `Reflect.get` instead of `target[prop]` preserves correct `this` binding,
+ * which matters for Pino's internal method calls.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/get
+ */
+export declare function createContextAwareLogger(baseLogger: Logger): Logger;
+/**
+ * Runs `fn` with a child logger active in AsyncLocalStorage.
+ * Any code that calls `logger.info(...)` inside `fn` (including library code)
+ * will see the provided `fields` on its log output.
+ *
+ * Creates a child of the current context logger (or base logger if none),
+ * so nested calls stack correctly.
+ *
+ * @example
+ * // In a NestJS interceptor:
+ * withLogContext({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
+ *   next.handle().subscribe(...);
+ * });
+ *
+ * // In a Lambda handler:
+ * withLogContext({ 'batch.id': batchId }, async () => {
+ *   await processBatch(items);
+ * });
+ */
+export declare function withLogContext<T>(fields: Record<string, unknown>, fn: () => T): T;

package/lib/logger/log-context.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggerStorage = void 0;
+exports.createContextAwareLogger = createContextAwareLogger;
+exports.withLogContext = withLogContext;
+const async_hooks_1 = require("async_hooks");
+/**
+ * Stores the current request-scoped child logger per async context.
+ * Used by `createContextAwareLogger` to make the `logger` export context-aware,
+ * and by `withLogContext` to set context for a block of code.
+ */
+exports.loggerStorage = new async_hooks_1.AsyncLocalStorage();
+let _baseLogger;
+/**
+ * Wraps a base Pino logger in a Proxy that is aware of AsyncLocalStorage context.
+ * Called once at module init — the returned Proxy becomes the `logger` export.
+ *
+ * When code calls `logger.info(...)`, the Proxy intercepts the property access:
+ * 1. Checks `loggerStorage.getStore()` for a request-scoped child logger
+ * 2. If found, delegates to the child (which has user/org/request fields baked in)
+ * 3. If not found (e.g. during startup), falls back to the base logger
+ *
+ * This means all 39+ library files that `import { logger } from '@contrail/telemetry'`
+ * automatically get request-scoped context without any import changes.
+ *
+ * @example
+ * // In telemetry/src/logger/index.ts (called once):
+ * export const logger = createContextAwareLogger(baseLogger);
+ *
+ * // In any library file:
+ * import { logger } from '@contrail/telemetry';
+ * logger.info('query executed'); // includes user.id, org.slug, etc. during a request
+ *
+ * ## How Proxy and Reflect work
+ *
+ * **Proxy** — wraps an object and intercepts operations (get, set, has, etc.).
+ * We only intercept `get` so that property reads (like `.info`, `.warn`, `.level`)
+ * are redirected to the context-appropriate logger.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
+ *
+ * **Reflect.get(target, prop, receiver)** — performs the default property read.
+ * Using `Reflect.get` instead of `target[prop]` preserves correct `this` binding,
+ * which matters for Pino's internal method calls.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/get
+ */
+function createContextAwareLogger(baseLogger) {
+    _baseLogger = baseLogger;
+    return new Proxy(baseLogger, {
+        get(target, prop, receiver) {
+            var _a;
+            const currentLogger = (_a = exports.loggerStorage.getStore()) !== null && _a !== void 0 ? _a : target;
+            return Reflect.get(currentLogger, prop, receiver);
+        },
+    });
+}
+/**
+ * Runs `fn` with a child logger active in AsyncLocalStorage.
+ * Any code that calls `logger.info(...)` inside `fn` (including library code)
+ * will see the provided `fields` on its log output.
+ *
+ * Creates a child of the current context logger (or base logger if none),
+ * so nested calls stack correctly.
+ *
+ * @example
+ * // In a NestJS interceptor:
+ * withLogContext({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
+ *   next.handle().subscribe(...);
+ * });
+ *
+ * // In a Lambda handler:
+ * withLogContext({ 'batch.id': batchId }, async () => {
+ *   await processBatch(items);
+ * });
+ */
+function withLogContext(fields, fn) {
+    var _a;
+    const parent = (_a = exports.loggerStorage.getStore()) !== null && _a !== void 0 ? _a : _baseLogger;
+    const child = parent.child(fields);
+    return exports.loggerStorage.run(child, fn);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/telemetry",
-  "version": "2.0.0-dev-telemetry-own-otel-1",
+  "version": "2.0.0",
   "description": "Telemetry and monitoring utilities for contrail services",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",