nlogs

Structured logger for Node.js with category-based filtering, AsyncLocalStorage trace IDs, and built-in timers and counters. Configurable through environment variables - no setup code in most cases.

Installation

Requires Node.js 20 or newer.

npm install nlogs

Quick start

import Logger from 'nlogs'

const logger = new Logger()

logger.info('server started', { port: 3000 })
logger.error(new Error('boom'))

The dark ANSI formatter is used in development and switches to json when NODE_ENV=production.

Log levels

trace -> debug -> log -> info -> warn -> error -> fatal

warn, error, and fatal are written to stderr; the rest go to stdout. fatal is always emitted regardless of filtering.

Filter at runtime:

NLOGS_LEVEL=warn node app.js          # warn, error, fatal
NLOGS_LEVELS=info,error node app.js   # exact set
NLOGS_LEVEL=off node app.js           # silence everything except fatal

Categories

Each logger instance has a category. By default it is derived from the source file path. Pass a class, an explicit string, or module/import.meta to override:

class UserService {}
const log = new Logger(UserService)

Filter categories with NLOGS_CATEGORY (syntax mirrors debug: comma-separated entries, leading - for negation, module:category for module-scoped rules, * for everything):

NLOGS_CATEGORY="auth, payments, -auth:internal" node app.js

Trace context

Logger.run opens an AsyncLocalStorage context. Every log inside the callback - and any async work it spawns - carries the same traceId and shared details.

A string argument sets the traceId directly:

Logger.run(req.headers['x-trace-id'], () => handler(req))

An object argument generates a fresh traceId and attaches arbitrary fields to details:

Logger.run({ userId: '42' }, async () => {
  logger.info('handling request')
  await processOrder()
})

Pass traceId explicitly to combine both:

Logger.run({ traceId: 'abc-123', userId: '42' }, () => handler())

Nested calls chain: the outer traceId is preserved in _traceIds.

Timers and counters

logger.time('db')
await query()
logger.timeEnd('db')

const counter = logger.count('events')
counter.log()    // increments and logs
counter.log()
counter.end()    // closes the counter

logger.time(label) and logger.count(label) return a handle with .log() and .end() methods. Calling the handle itself (counter()) is equivalent to .end(). Without a label each call returns a fresh handle. Repeated logger.count(label) with the same label keeps incrementing the same counter until .end().

Formatters

Value	When to use
dark	Terminal with dark background (default)
light	Terminal with light background
string	Plain text, no ANSI
json	One JSON object per line (prod default)

Override with NLOGS_FORMATTER.

Environment variables

Naming convention: NLOGS_* (preferred), LOGGER_* (fallback), unprefixed (compatibility with DEBUG, LEVEL, CATEGORY, ...).

Variable	Purpose
NLOGS_PROJECT	Project name in meta
NLOGS_SERVICE	Service name in meta
NLOGS_CATEGORY	Category allow/deny list
NLOGS_DEBUG	Same syntax for debug/trace levels
NLOGS_LEVEL	Minimum level (or exact level)
NLOGS_LEVELS	Exact set of allowed levels
NLOGS_FORMATTER	json/string/light/dark
NLOGS_STRICT_LEVEL_RULES	Pre-filter by level (bool)

DEBUG=* and NODE_DEBUG=* are honoured as aliases for NLOGS_DEBUG.

NestJS adapter

import { NestjsLogger } from 'nlogs'

const app = await NestFactory.create(AppModule, {
  logger: new NestjsLogger(),
})

Template logger

TemplateLogger injects a fixed template applied to every message. Use it as a tagged template literal where each ${...} can be a plain value or a function that receives the current LogInfo and returns the substituted value:

import { TemplateLogger } from 'nlogs'

const logger = new TemplateLogger('http')
logger.template`[${info => info.meta.level}] ${info => info.message}`

logger.info('request received')

License

MIT - see LICENSE.