@contrail/telemetry 2.0.0-dev-telemetry-own-otel-2 → 2.0.1-alpha-log-serialization-1

package/CHANGELOG.md

@@ -7,6 +7,27 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-04-14
+
+### Fixed
+
+- **Error serialization** — `logger.error({ error }, 'msg')` and any other arbitrary key holding an `Error` object now serialize correctly (type, message, stack, enumerable properties) instead of logging `{}`. Handled via a `logMethod` hook that detects `Error` instances in the mergeObject and applies `pino.stdSerializers.err` before pino serializes. The `err` key (pino's built-in) and bare Error passed as the first argument were already working and continue to work unchanged.
+
+## [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

@@ -3,6 +3,7 @@ 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 pinoErrorSerializationHooks: pino.LoggerOptions['hooks'];
 export declare const baseLogger: pino.Logger<never, boolean>;
 export declare const logger: pino.Logger;
 /**

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.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.logger = exports.baseLogger = exports.pinoErrorSerializationHooks = 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"));
@@ -111,7 +111,7 @@ function createOtelStream() {
             var _a, _b;
             try {
                 const logRecord = JSON.parse(chunk.toString());
-                const { level, ...attributes } = logRecord;
+                const { level, [semantic_conventions_2.ATTR_LOG_MESSAGE]: message, ...attributes } = logRecord;
                 const activeSpan = api_1.trace.getSpan(api_1.context.active());
                 const spanContext = activeSpan === null || activeSpan === void 0 ? void 0 : activeSpan.spanContext();
                 const spanAttributes = getSpanAttributes(activeSpan);
@@ -129,7 +129,7 @@ function createOtelStream() {
                 otelLogger.emit({
                     severityNumber: (_a = logger_config_1.PINO_LEVEL_TO_OTEL_SEVERITY[level]) !== null && _a !== void 0 ? _a : api_logs_1.SeverityNumber.INFO,
                     severityText: (_b = logger_config_1.PINO_LEVEL_TO_NAME[level]) !== null && _b !== void 0 ? _b : 'INFO',
-                    body: attributes[semantic_conventions_2.ATTR_LOG_MESSAGE],
+                    body: message,
                     // Attribute precedence (last-spread-wins):
                     // 1. safeAttributes — flattened user/log-context attributes (lowest priority)
                     // 2. lambdaEnvAttributes — static Lambda env attributes (override user attrs)
@@ -222,11 +222,71 @@ function getLambdaRequestId() {
     }
 }
 // --- Base Pino Logger ---
+// --- Error Serialization Hooks ---
+/**
+ * Exported so tests can create a standalone pino instance with the same hooks.
+ *
+ * Fixes: Error objects passed under arbitrary keys (e.g. `{ error }`, `{ cause }`)
+ * serialize as `{}` because Error properties are non-enumerable.
+ *
+ * Pino already handles:
+ *   - `{ err }` — via its default `serializers.err` (stdSerializers.err)
+ *   - `logger.error(error, 'msg')` — pino wraps bare Error as `{ err: error }` internally
+ *
+ * This hook covers the remaining cases: any key whose value is an Error instance.
+ * It shallow-copies the mergeObject to avoid mutating the caller's object.
+ */
+/**
+ * Walks a pino mergeObject and returns a new object with any Error-valued keys
+ * serialized via pino.stdSerializers.err. Returns null if no Errors are found
+ * (caller should use the original object unchanged).
+ *
+ * Skips the 'err' key — pino serializes it natively via its default serializers.err.
+ * Pre-serializing it here would cause double-serialization (plain object → type: "Object").
+ */
+function serializeErrorsInMergeObject(mergeObject) {
+    let transformed = null;
+    for (const [key, value] of Object.entries(mergeObject)) {
+        if (!(value instanceof Error))
+            continue;
+        if (key === 'err')
+            continue;
+        if (!transformed)
+            transformed = { ...mergeObject };
+        transformed[key] = pino_1.default.stdSerializers.err(value);
+    }
+    return transformed;
+}
+exports.pinoErrorSerializationHooks = {
+    logMethod(inputArgs, method) {
+        if (inputArgs.length === 0)
+            return method.apply(this, inputArgs);
+        const [firstArg, ...rest] = inputArgs;
+        if (firstArg === null || firstArg === undefined) {
+            return method.apply(this, inputArgs);
+        }
+        if (firstArg instanceof Error) {
+            // Pino handles this internally: it wraps the bare Error as { err: error }
+            // before calling logMethod, so this branch is never actually reached.
+            // Guard is here for clarity and safety.
+            return method.apply(this, inputArgs);
+        }
+        if (typeof firstArg !== 'object') {
+            return method.apply(this, inputArgs);
+        }
+        const transformed = serializeErrorsInMergeObject(firstArg);
+        if (transformed) {
+            return method.apply(this, [transformed, ...rest]);
+        }
+        return method.apply(this, inputArgs);
+    },
+};
 exports.baseLogger = (0, pino_1.default)({
     level: (_g = process.env.LOG_LEVEL) !== null && _g !== void 0 ? _g : 'debug',
     messageKey: semantic_conventions_2.ATTR_LOG_MESSAGE,
     timestamp: pino_1.default.stdTimeFunctions.isoTime,
     nestedKey: semantic_conventions_2.ATTR_LOG_PAYLOAD,
+    hooks: exports.pinoErrorSerializationHooks,
     base: {
         [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
         [semantic_conventions_4.ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: deploymentEnvironment,
@@ -261,10 +321,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

@@ -1,5 +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

@@ -4,8 +4,45 @@ 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, {
@@ -16,6 +53,25 @@ function createContextAwareLogger(baseLogger) {
         },
     });
 }
+/**
+ * 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;

package/package.json

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