@contrail/telemetry 2.0.2 → 2.0.4-alpha.1

package/CHANGELOG.md

@@ -7,7 +7,20 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [2.0.1] - 2026-04-15
+## [2.0.4] - 2026-04-15
+
+### Added
+
+- **Duplicate module detection** — logs a `stderr` warning at cold start if two copies of `@contrail/telemetry` are loaded, so silent log loss and broken context propagation are immediately visible.
+
+## [2.0.3] - 2026-04-15
+
+### Changed
+
+- **`withLogContext` renamed to `withLogAttributes`** — Aligns the export name with the API documented in 2.0.0. Any code importing `withLogContext` directly must update to `withLogAttributes`.
+- **`addStream` fixed** — Uses `pino.symbols.streamSym` to access the underlying multistream, replacing an internal `(logger as any).stream` access that broke across pino versions.
+
+## [2.0.2] - 2026-04-15
 
 ### Fixed
 
@@ -18,7 +31,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### 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.
+- **`withLogAttributes(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.

package/lib/logger/index.d.ts

@@ -2,7 +2,7 @@ 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 { loggerStorage, withLogAttributes } from './log-context';
 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.withLogAttributes = 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"));
@@ -31,7 +31,31 @@ Object.defineProperty(exports, "ATTR_LOG_MESSAGE", { enumerable: true, get: func
 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; } });
+Object.defineProperty(exports, "withLogAttributes", { enumerable: true, get: function () { return log_context_1.withLogAttributes; } });
+// --- Singleton Guard ---
+// The logger uses AsyncLocalStorage for request context propagation. If two copies
+// of this module are loaded (e.g. due to a version mismatch causing npm to install
+// a nested duplicate), each copy has its own AsyncLocalStorage instance and its own
+// OTel LoggerProvider. Context set in one copy won't be visible in the other, and
+// flushLogs() will only flush the provider it closes over — silently dropping logs.
+//
+// Symbol.for uses the global symbol registry, which is shared across all module
+// instances, so this check fires correctly even when two copies are loaded.
+//
+// Local dev note: running `npm i` inside a lib package directory causes npm v7+ to
+// auto-install peer deps locally. If that package is then symlinked into a service,
+// the nested node_modules travels with it and re-creates the duplicate. Published
+// tarballs don't ship node_modules, so this is local-only.
+const TELEMETRY_SINGLETON_KEY = Symbol.for('@contrail/telemetry/logger-initialized');
+if (global[TELEMETRY_SINGLETON_KEY]) {
+    process.stderr.write('[WARN] @contrail/telemetry loaded twice — duplicate module instance detected. ' +
+        'flushLogs() will only flush one provider and log context may not propagate correctly. ' +
+        'Ensure @contrail/telemetry is listed as a peerDependency in any library that re-exports ' +
+        'it, and that the host service lists it in its own package.json.\n');
+}
+else {
+    global[TELEMETRY_SINGLETON_KEY] = true;
+}
 // --- Environment & Resource Setup ---
 const semantic_conventions_4 = require("../semantic-conventions");
 const LAMBDA_ENV_OTEL_ATTRIBUTES = getLambdaEnvAttributes();
@@ -243,7 +267,8 @@ exports.logger = (0, log_context_2.createContextAwareLogger)(exports.baseLogger)
  * Use this to wire additional log sinks (e.g. InMemoryLogStream in app-framework).
  */
 function addStream(streamEntry) {
-    const ms = exports.baseLogger.stream;
+    const streamSym = pino_1.default.symbols.streamSym;
+    const ms = exports.baseLogger[streamSym];
     if (ms && typeof ms.add === 'function') {
         ms.add(streamEntry);
     }

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

@@ -3,7 +3,7 @@ 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.
+ * and by `withLogAttributes` to set context for a block of code.
  */
 export declare const loggerStorage: AsyncLocalStorage<Logger>;
 /**
@@ -49,13 +49,13 @@ export declare function createContextAwareLogger(baseLogger: Logger): Logger;
  *
  * @example
  * // In a NestJS interceptor:
- * withLogContext({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
+ * withLogAttributes({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
  *   next.handle().subscribe(...);
  * });
  *
  * // In a Lambda handler:
- * withLogContext({ 'batch.id': batchId }, async () => {
+ * withLogAttributes({ 'batch.id': batchId }, async () => {
  *   await processBatch(items);
  * });
  */
-export declare function withLogContext<T>(fields: Record<string, unknown>, fn: () => T): T;
+export declare function withLogAttributes<T>(fields: Record<string, unknown>, fn: () => T): T;

package/lib/logger/log-context.js

@@ -2,12 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loggerStorage = void 0;
 exports.createContextAwareLogger = createContextAwareLogger;
-exports.withLogContext = withLogContext;
+exports.withLogAttributes = withLogAttributes;
 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.
+ * and by `withLogAttributes` to set context for a block of code.
  */
 exports.loggerStorage = new async_hooks_1.AsyncLocalStorage();
 let _baseLogger;
@@ -63,16 +63,16 @@ function createContextAwareLogger(baseLogger) {
  *
  * @example
  * // In a NestJS interceptor:
- * withLogContext({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
+ * withLogAttributes({ user: { id: 'abc' }, url: { path: '/api/items' } }, () => {
  *   next.handle().subscribe(...);
  * });
  *
  * // In a Lambda handler:
- * withLogContext({ 'batch.id': batchId }, async () => {
+ * withLogAttributes({ 'batch.id': batchId }, async () => {
  *   await processBatch(items);
  * });
  */
-function withLogContext(fields, fn) {
+function withLogAttributes(fields, fn) {
     var _a;
     const parent = (_a = exports.loggerStorage.getStore()) !== null && _a !== void 0 ? _a : _baseLogger;
     const child = parent.child(fields);

package/package.json

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