Structured Logger

Reusable structured logging toolkit wrapping Pino with correlation IDs, daily rotation, and human-friendly console output.

Highlights

• TypeScript-first API with strongly typed LogCategory, LogLevelName, and structured event payloads.
• Automatically captures the calling function name for richer context in every record.
• AsyncLocalStorage correlation IDs via withCorrelationId / bindCorrelationId.
• Pretty, multi-line console JSON (with ANSI colours) and compact, grep-friendly file output.
• Pino-based dispatcher that fans out to colourised console logs and daily rotating files (with compression and retention).
• Pluggable dispatchers; ship your own by implementing the LogDispatcher interface.

Installation

npm install @developerzava/structured-logger
# or
yarn add @developerzava/structured-logger

Add Pino if it is not already present:

npm install pino

Quick Start

import { createStructuredLogger, LogCategory, withCorrelationId } from "@developerzava/structured-logger";

const logger = createStructuredLogger("OrderExecutor", {
  defaultDetails: { service: "order-service" },
});

await withCorrelationId(async () => {
  logger.info({
    category: LogCategory.TRADING,
    action: "OrderPlaced",
    message: "Submitted order to exchange",
    details: { symbol: "AAPL", side: "buy", qty: 100 },
  });
});

Log Output

Console output is pretty-printed JSON with colours when TTY is detected. The timestamp is exposed as date, the message as msg, and the caller function is captured automatically when available:

{
  "date": "2024-05-05T12:00:00.000Z",
  "level": "INFO",
  "category": "TRADING",
  "function": "placeOrder",
  "component": "OrderExecutor",
  "action": "OrderPlaced",
  "correlationId": "tx-abc123",
  "msg": "Submitted order to exchange",
  "details": {
    "symbol": "AAPL",
    "side": "buy",
    "qty": 100,
    "service": "order-service"
  }
}

File output stays single-line and compact for grep/rotation-friendly logs:

2024-05-05T12:00:00.000Z  [INFO -  TRADING]  OrderExecutor:  placeOrder OrderPlaced correlationId=tx-abc123 msg="Submitted order to exchange" details={"symbol":"AAPL","side":"buy","qty":100,"service":"order-service"}

Customising Output

• Override the dispatcher once during startup to tweak destinations:

import { setDispatcher, PinoLogDispatcher } from "@developerzava/structured-logger";

setDispatcher(
  new PinoLogDispatcher({
    logDirectory: "/var/log/trading-bot",
    filenamePrefix: "trader",
    retentionDays: 14,
    compressAfterDays: 2,
    enableConsole: process.env.NODE_ENV !== "production",
  }),
);

• Implement your own dispatcher by providing { log(level, record), flush() }.

Correlation IDs

Wrap each logical task with withCorrelationId (HTTP request handlers, job runners). If no correlation ID is bound, the logger generates one automatically.

Building Locally

npm install
npm run build

The compiled artefacts live in dist/ and include both ESM and CommonJS entry points plus type declarations.