@zenvia/logger 1.6.2 → 2.0.0

package/.github/workflows/npm-publish.yml

@@ -11,10 +11,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
-          node-version: 18
+          node-version: '24'
       - name: Install dependencies
         run: npm ci
       - name: Run lint
@@ -30,13 +30,14 @@ jobs:
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
-          node-version: 18
-          registry-url: https://registry.npmjs.org/
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
       - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: NODE_AUTH_TOKEN="" npm publish --provenance

package/README.md

@@ -1,14 +1,19 @@
 # Zenvia Logger for Node.js
 
-A wrapper for [Winston](https://github.com/winstonjs/winston) Logging [Node.js](https://nodejs.org/) library that formats the output on STDOUT as [Logstash](https://www.elastic.co/logstash) JSON format. Since version 1.5.0 it is possible to use log tracking. Zenvia Logger uses the [cls-trace](https://www.npmjs.com/package/cls-rtracer) to perform the tracking
+A wrapper for [Winston](https://github.com/winstonjs/winston) Logging [Node.js](https://nodejs.org/) library that formats the output on STDOUT as [Logstash](https://www.elastic.co/logstash) JSON format.
+
+**Main features:**
+- **Dual Package Support:** Native support for both **ES Modules (ESM)** and **CommonJS (CJS)**.
+- **Node 24 Ready:** Optimized for native TypeScript execution (Type Stripping).
+- **Distributed Tracing:** Automated request tracking using [cls-rtracer](https://www.npmjs.com/package/cls-rtracer).
 
 [![License](https://img.shields.io/github/license/zenvia/zenvia-logger-node.svg)](LICENSE.md)
-[![Build Status](https://travis-ci.com/zenvia/zenvia-logger-node.svg?branch=master)](https://travis-ci.com/zenvia/zenvia-logger-node)
+[![NPM Version](https://img.shields.io/npm/v/%40zenvia%2Flogger)](https://www.npmjs.com/package/@zenvia/logger)
 [![Coverage Status](https://coveralls.io/repos/github/zenvia/zenvia-logger-node/badge.svg?branch=master)](https://coveralls.io/github/zenvia/zenvia-logger-node?branch=master)
-[![Dependencies](https://img.shields.io/david/zenvia/zenvia-logger-node.svg)](https://david-dm.org/zenvia/zenvia-logger-node)
 
-[![Twitter Follow](https://img.shields.io/twitter/follow/ZENVIA_.svg?style=social)](https://twitter.com/intent/follow?screen_name=ZENVIA_)
+[![NPM](https://nodei.co/npm/@zenvia/logger.svg)](https://nodei.co/npm/@zenvia/logger/)
 
+[![Twitter Follow](https://img.shields.io/twitter/follow/ZENVIA_.svg?style=social)](https://twitter.com/intent/follow?screen_name=ZENVIA_)
 
 
 ## Installation
@@ -101,7 +106,7 @@ Output:
 }
 ```
 
-### Available logging levels
+## Available logging levels
 
 The log levels are as follows.
 
@@ -115,7 +120,7 @@ For backward compatibility purposes, **"verbose"** and **"silly"** levels will b
 
 
 
-### Adding extra key/value fields
+## Adding extra key/value fields
 
 ```js
 logger.debug('Some text message', { keyA: 'value A', keyB: 'value B' });
@@ -135,7 +140,7 @@ Output:
 }
 ```
 
-### Logging errors
+## Logging errors
 
 ```js
 logger.error('Ops!', new Error('Something goes wrong'));
@@ -174,7 +179,7 @@ Output:
 }
 ```
 
-### Using trace logs
+## Using trace logs
 From version 1.5.0 it is possible to track logs. To do traceability, the cls-rTrace package is used. To use it, just add the middleware in the framework you are using. In this way it is possible to propagate the traceId received in a request to the logs throughout your project. If no traceId is passed in the request, Zenvia Logger generates a random traceId for the request being processed.
 
 **Request example sending traceId:**
@@ -218,6 +223,61 @@ Log Output
 }
 ```
 
+## Contextual Logging (Async Context)
+
+You can use `runWithContext` and `addContext` to manage metadata context across asynchronous flows (like Kafka consumers or complex background jobs). This ensures all logs within a specific execution thread share the same context without passing a logger instance manually.
+
+### Basic Usage with runWithContext
+
+Useful for isolating logs from different event sources or partitions.
+
+```js
+import logger from '@zenvia/logger';
+
+async function handleEvent(event) {
+  await logger.runWithContext({
+    partition: event.partition,
+    topic: 'orders-topic'
+  }, async () => {
+    // All logs here will include partition and topic automatically
+    logger.info('Processing started');
+    await processOrder(event.data);
+  });
+}
+```
+
+### Enriching Context with addContext
+
+You can inject new metadata into the current context at any point during the execution.
+
+```js
+import logger from '@zenvia/logger';
+
+async function processOrder(data) {
+  logger.info('Validating...');
+
+  const provider = await api.getProvider(data.id);
+
+  // Mutates the current context to include providerId in all subsequent logs
+  logger.addContext({ providerId: provider.id });
+
+  logger.info('Validation complete');
+  // Output JSON will contain: partition, topic AND providerId
+}
+```
+
+### Nested Contexts
+
+Contexts can be nested. The inner context will inherit metadata from the parent.
+
+```js
+await logger.runWithContext({ level1: 'A' }, async () => {
+  await logger.runWithContext({ level2: 'B' }, async () => {
+    logger.info('Log with A and B');
+  });
+});
+```
+
 ## License
 
 [MIT](LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenvia/logger",
-  "version": "1.6.2",
+  "version": "2.0.0",
   "description": "A wrapper for Winston Logging Node.js library that formats the output on STDOUT as Logstash JSON format.",
   "license": "MIT",
   "main": "./src/index",
@@ -31,19 +31,22 @@
     "Zenvia",
     "Winston"
   ],
+  "engines": {
+    "node": ">=16.4.0"
+  },
   "dependencies": {
     "app-root-dir": "^1.0.2",
     "cls-rtracer": "^2.6.3",
-    "winston": "^3.11.0"
+    "winston": "^3.19.0"
   },
   "devDependencies": {
     "chai": "^4.2.0",
     "chai-as-promised": "^7.1.1",
-    "coveralls": "^3.1.0",
+    "coveralls-next": "^6.0.1",
     "eslint": "^7.10.0",
     "eslint-config-airbnb-base": "^14.2.0",
     "eslint-plugin-import": "^2.22.1",
-    "mocha": "^8.1.3",
+    "mocha": "^11.7.5",
     "nyc": "^15.1.0",
     "sinon": "^9.2.0",
     "sinon-chai": "^3.5.0",

package/src/index.d.ts

@@ -1,2 +1,12 @@
-export { default } from './lib/logger';
-export { default as traceMiddleware } from './middleware/trace';
+
+import { ZenviaLogger } from './lib/logger';
+import traceMiddlewareFactory from './middleware/trace';
+
+type TraceMiddlewareInstance = ReturnType<typeof traceMiddlewareFactory>;
+type ZenviaLoggerModule = ZenviaLogger & {
+  default: ZenviaLogger;
+  traceMiddleware: TraceMiddlewareInstance;
+};
+
+declare const loggerModule: ZenviaLoggerModule;
+export = loggerModule;

package/src/index.js

@@ -1,9 +1,9 @@
-Object.defineProperty(exports, '__esModule', {
-  value: true,
-});
-
 const logger = require('./lib/logger');
-const traceMiddleware = require('./middleware/trace');
+const traceMiddlewareFactory = require('./middleware/trace');
+
+const traceMiddleware = traceMiddlewareFactory();
 
-exports.default = logger;
-exports.traceMiddleware = traceMiddleware();
+module.exports = logger;
+module.exports.logger = logger;
+module.exports.traceMiddleware = traceMiddleware;
+module.exports.default = logger;

package/src/lib/logger.d.ts

@@ -1,8 +1,10 @@
 import { Logger, LeveledLogMethod } from 'winston';
 
-interface ZenviaLogger extends Logger {
+export interface ZenviaLogger extends Logger {
   fatal: LeveledLogMethod;
   isFatalEnabled(): boolean;
+  runWithContext<T>(context: object, fn: () => Promise<T> | T): Promise<T>;
+  addContext(context: object): void;
 }
 
 declare const logger: ZenviaLogger;

package/src/lib/logger.js

@@ -7,9 +7,12 @@ const winston = require('winston');
 const path = require('path');
 const appRootDir = require('app-root-dir').get();
 const rTrace = require('cls-rtracer');
+const { AsyncLocalStorage } = require('node:async_hooks');
 
 const appPackage = require(path.join(appRootDir, 'package'));
 
+const loggerStorage = new AsyncLocalStorage();
+
 const customFormatJson = winston.format((info) => {
   let stack;
 
@@ -55,7 +58,7 @@ const createConsoleTransport = () => new winston.transports.Console({
   stderrLevels: ['fatal', 'error'],
 });
 
-const logger = winston.createLogger({
+const baseLogger = winston.createLogger({
   levels: {
     fatal: 0,
     error: 1,
@@ -74,6 +77,11 @@ const logger = winston.createLogger({
   exitOnError: false,
 });
 
+function getActiveLogger() {
+  const store = loggerStorage.getStore();
+  return store ? store.current : baseLogger;
+}
+
 function leveledLogFn(level) {
   return function log(...args) {
     return logFn(level, ...args);
@@ -81,8 +89,9 @@ function leveledLogFn(level) {
 }
 
 function logFn(level, msg) {
+  const currentLogger = getActiveLogger();
   if (arguments.length === 1 && typeof level !== 'object') {
-    return logger;
+    return currentLogger;
   }
   if (arguments.length === 2) {
     if (msg && typeof msg === 'object') {
@@ -93,24 +102,43 @@ function logFn(level, msg) {
       };
     }
   }
-  return logger.realLog(...arguments);
+  return currentLogger.log(...arguments);
 }
 
 function isLevelEnabledFn(level) {
   return function isLevelEnabled() {
-    return logger.isLevelEnabled(level);
+    return getActiveLogger().isLevelEnabled(level);
   };
 }
 
-logger.fatal = leveledLogFn('fatal');
-logger.error = leveledLogFn('error');
-logger.warn = leveledLogFn('warn');
-logger.info = leveledLogFn('info');
-logger.debug = leveledLogFn('debug');
-logger.verbose = leveledLogFn('verbose');
-logger.silly = leveledLogFn('silly');
-logger.isFatalEnabled = isLevelEnabledFn('fatal');
-logger.realLog = logger.log;
-logger.log = logFn;
+const logger = {
+  ...baseLogger,
+
+  fatal: leveledLogFn('fatal'),
+  error: leveledLogFn('error'),
+  warn: leveledLogFn('warn'),
+  info: leveledLogFn('info'),
+  debug: leveledLogFn('debug'),
+  verbose: leveledLogFn('verbose'),
+  silly: leveledLogFn('silly'),
+  log: logFn,
+  isFatalEnabled: isLevelEnabledFn('fatal'),
+
+  runWithContext: (context, fn) => {
+    const parentLogger = loggerStorage.getStore()?.current || baseLogger;
+    const child = parentLogger.child(context);
+    return loggerStorage.run({ current: child }, fn);
+  },
+
+  addContext: (context) => {
+    const store = loggerStorage.getStore();
+    if (store) {
+      store.current = store.current.child(context);
+    } else {
+      baseLogger.warn('Attempted to call addContext outside of an AsyncLocalStorage context');
+    }
+  },
+};
 
 module.exports = logger;
+module.exports.default = logger;

package/src/middleware/trace.d.ts

@@ -1,9 +1,10 @@
 import rTracer from 'cls-rtracer';
 
-declare const traceMiddleware: () =>
+export type TracerMiddlewareResult =
   ReturnType<typeof rTracer.expressMiddleware> |
   ReturnType<typeof rTracer.fastifyPlugin> |
   typeof rTracer.hapiPlugin |
   ReturnType<typeof rTracer.koaMiddleware>;
 
-export default traceMiddleware;
+declare const traceMiddlewareFactory: () => TracerMiddlewareResult;
+export default traceMiddlewareFactory;

package/src/middleware/trace.js

@@ -1,6 +1,6 @@
 const rTracer = require('cls-rtracer');
 
-module.exports = () => {
+const traceMiddlewareFactory = () => {
   const frameworkMiddleware = process.env.LOGGING_FRAMEWORK_MIDDLEWARE;
 
   const RTRACER_OPTIONS = {
@@ -23,3 +23,7 @@ module.exports = () => {
 
   return middleware[frameworkMiddleware || 'EXPRESS'];
 };
+
+module.exports = traceMiddlewareFactory;
+module.exports.traceMiddleware = traceMiddlewareFactory;
+module.exports.default = traceMiddlewareFactory;

package/test/lib/logger.spec.js

@@ -299,4 +299,89 @@ describe('Logger test', () => {
       obj.should.not.have.property('level');
     });
   });
+
+  describe('Contextual Logging (AsyncLocalStorage)', () => {
+    it('should maintain context metadata across async calls using runWithContext', async () => {
+      await logger.runWithContext({ partition: 1024, topic: 'my-topic' }, async () => {
+        await Promise.resolve();
+
+        logger.info('message inside context');
+
+        const output = JSON.parse(stdMocks.flush().stdout[0]);
+        output.should.have.property('partition').and.be.equal(1024);
+        output.should.have.property('topic').and.be.equal('my-topic');
+        output.should.have.property('message').and.be.equal('message inside context');
+      });
+    });
+
+    it('should update context metadata using addContext (mutation)', async () => {
+      await logger.runWithContext({ requestId: 'initial-id' }, async () => {
+        logger.info('first log');
+        const output1 = JSON.parse(stdMocks.flush().stdout[0]);
+        output1.should.not.have.property('providerId');
+
+        logger.addContext({ providerId: 'zenvia-123' });
+
+        logger.info('second log');
+        const output2 = JSON.parse(stdMocks.flush().stdout[0]);
+        output2.should.have.property('requestId').and.be.equal('initial-id');
+        output2.should.have.property('providerId').and.be.equal('zenvia-123');
+      });
+    });
+
+    it('should warn when addContext is called outside of an active context', () => {
+      logger.addContext({ some: 'data' });
+
+      const actualOutput = stdMocks.flush().stdout[0];
+      const parsedOutput = JSON.parse(actualOutput);
+
+      parsedOutput.should.have.property('level').and.be.equal('WARN');
+      parsedOutput.should.have.property('message').and.be.equal('Attempted to call addContext outside of an AsyncLocalStorage context');
+    });
+
+    it('should isolate contexts between concurrent executions', async () => {
+      const flow1 = logger.runWithContext({ flow: 1 }, async () => {
+        await Promise.resolve();
+        logger.info('log flow 1');
+      });
+
+      const flow2 = logger.runWithContext({ flow: 2 }, async () => {
+        await Promise.resolve();
+        logger.info('log flow 2');
+      });
+
+      await Promise.all([flow1, flow2]);
+
+      const logs = stdMocks.flush().stdout.map((line) => JSON.parse(line));
+
+      const logFlow2 = logs.find((l) => l.message === 'log flow 2');
+      const logFlow1 = logs.find((l) => l.message === 'log flow 1');
+
+      logFlow2.should.have.property('flow').and.be.equal(2);
+      logFlow1.should.have.property('flow').and.be.equal(1);
+    });
+
+    it('should not leak metadata to logs outside of context', async () => {
+      await logger.runWithContext({ internal: 'secret' }, async () => {
+        logger.info('inside');
+      });
+
+      logger.info('outside');
+
+      const outputs = stdMocks.flush().stdout.map((line) => JSON.parse(line));
+      outputs[0].should.have.property('internal').and.be.equal('secret');
+      outputs[1].should.not.have.property('internal');
+    });
+
+    it('should allow nested contexts (re-nesting via runWithContext)', async () => {
+      await logger.runWithContext({ level1: 'a' }, async () => {
+        await logger.runWithContext({ level2: 'b' }, async () => {
+          logger.info('nested log');
+          const output = JSON.parse(stdMocks.flush().stdout[0]);
+          output.should.have.property('level1').and.be.equal('a');
+          output.should.have.property('level2').and.be.equal('b');
+        });
+      });
+    });
+  });
 });