@ai-digital-factory/logging

Provider-neutral structured logging for TypeScript services. The package exposes a small logging API and Express middleware while keeping Pino and the current log provider internal.

Install

pnpm add @ai-digital-factory/logging

The package requires Node.js 22 or newer. Ask the logging package maintainer for LOG_INGESTION_URL and LOG_CREDENTIAL; treat both as secrets and keep them outside source control.

Express quick start

import express from "express";
import { createLogManager } from "@ai-digital-factory/logging";

const logs = createLogManager({
  service: "orders-api",
  environment: process.env.NODE_ENV ?? "development",
  connection: {
    ingestionUrl: process.env.LOG_INGESTION_URL!,
    credential: process.env.LOG_CREDENTIAL!,
  },
  redact: ["password", "customer.email", "error.stack"],
});

const app = express();
app.use(logs.expressMiddleware());

app.get("/orders/:id", (req, res) => {
  req.log.info({ orderId: req.params.id }, "Fetching order");
  res.json({ id: req.params.id });
});

const server = app.listen(3000, () => {
  logs.logger.info({ port: 3000 }, "Server started");
});

async function stop() {
  server.close(async () => {
    await logs.shutdown({ timeoutMs: 5_000 });
  });
}
process.once("SIGINT", stop);
process.once("SIGTERM", stop);

The middleware assigns a fresh request ID, returns it as x-request-id, adds req.log, and emits a completion record containing only method, route template, status, duration, and whether the connection ended early. It never captures headers, query strings, request bodies, or existing console calls.

Logging API

All six methods accept either a message or structured fields followed by a message:

logs.logger.info("Worker started");
logs.logger.warn({ queueDepth: 200 }, "Queue is backing up");
logs.logger.error({ error }, "Order failed");

const jobLog = logs.logger.child({ job: "order-sync" });
jobLog.debug({ batch: 4 }, "Processing batch");

Supported levels are trace, debug, info, warn, error, and fatal. The default threshold is info. Child fields are immutable context for that child and do not affect its parent. Native Error values at the top level of structured fields are serialized consistently.

Redaction paths are relative to structured fields. Values are replaced with [Redacted]. Avoid logging credentials at all; the SDK never includes its connection credential in diagnostics.

Delivery behavior

Delivery is asynchronous and best-effort. The defaults retain at most 1,000 records, 1 MiB in total, and 64 KiB per record; send batches of up to 100 every second; retry transient failures twice; and time out each request after five seconds. New records are dropped when a limit is reached.

Use onDiagnostic to observe retries and dropped records without sending those diagnostics through the same log destination:

const logs = createLogManager({
  // ...
  onDiagnostic(event) {
    process.stderr.write(`[logging] ${event.code}: ${event.reason} (${event.count})\n`);
  },
});

flush() attempts to drain the current buffer. shutdown() stops accepting records and attempts one bounded final flush. Both return { completed, pending }. A process crash or extended provider outage can lose logs; this package is not an audit trail.

For exact contracts, operational rules, and instructions for coding agents, see the repository's consumer integration guide.