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

``bash
npm install @developerzava/structured-logger


or


yarn add @developerzava/structured-logger
`

Add Pino if it is not already present:

`bash
npm install pino
`

Quick Start

`ts
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:

`json
{
"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"}
`

Timestamps are UTC by default (the trailing Z). To render timestamps in local time, configure timestampFormat: "local" (or set LOG_TIMESTAMP_FORMAT=local), which outputs an ISO-8601 offset timestamp such as 2024-05-05T08:00:00.000-04:00.

Customising Output

- Override the dispatcher once during startup to tweak destinations:

`ts
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",
timestampFormat: "local",
}),
);
`

- 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

`bash
npm install
npm run build
`

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