tslog

The overwrite.* object from v4 has been removed. Its functionality is now split into two distinct extension points:

1. logger.use(middleware): Use this to enrich or rewrite the LogContext before the record is built. You can modify ctx.args, ctx.meta, or drop a log entirely by returning null or false. This replaces overwrite.addMeta, overwrite.toLogObj, and overwrite.addPlaceholders.

2. Custom Transport with format: Use this to control the final output shape and destination. This replaces overwrite.transportJSON and overwrite.transportFormatted. You can provide a LogFormatter to the format property to define how the record is turned into a string/object before being passed to write.

Mapping Summary:

• overwrite.mask(args) $\rightarrow$ middleware or built-in mask group.
• overwrite.addMeta(...) $\rightarrow$ middleware writing to ctx.meta.
• overwrite.transportJSON(...) $\rightarrow$ Transport with format: "json".

// Example: Using middleware to add metadata and filter levels
const log = new Logger();
log.use((ctx) => {
  // metadata is attached under _logMeta
  ctx.meta.traceId = getTraceId();
  // drop logs below INFO (level 3)
  return ctx.logLevelId >= 3 ? ctx : null;
});

// Example: Custom transport with a JSON formatter
import type { LogFormatter } from "tslog";

const log = new Logger();
log.attachTransport({
  name: "backend",
  format: "json",
  write: (_record, line) => myBackend.send(line),
});

While the main tslog package is designed to work automatically in most environments, specific use cases can benefit from specialized builds. All builds share the same settings language and JSON shape.

tslog provides specific features to support AI agents and LLM applications:

• llms.txt: The package includes an llms.txt file to provide agents with a condensed API surface.
• Fields-first calls: Encourages structured, queryable logs for tool calls and traces.
• isLevelEnabled(level): Use this to guard expensive payload generation (like large prompts or token counts) so they are only computed if the log level is active.
• Request/Agent Correlation: Use runInContext(ctx, fn) to attach correlation IDs (like requestId) to all logs within a callback. This uses Node's AsyncLocalStorage and propagates automatically on Node, Deno, and Bun.

Note for Cloudflare Workers: Since AsyncLocalStorage cannot be auto-resolved, you must manually inject it via the contextStorage setting using the nodejs_als or nodejs_compat compatibility flag.

// Guard expensive payloads
if (log.isLevelEnabled("DEBUG")) {
  log.debug({ prompt: buildExpensivePrompt() });
}

// Correlate logs within a context
await log.runInContext({ requestId: "abc123" }, async () => {
  log.info("handling request"); // _logMeta carries requestId
  await doWork();
});

// Manual context injection for environments like Cloudflare Workers
import { AsyncLocalStorage } from "node:async_hooks";
const log = new Logger({ contextStorage: new AsyncLocalStorage() });

In browser environments, pretty.passObjectsNatively is on by default. This allows non-Error arguments to be passed to the console method by reference. This means DevTools will render objects and arrays as collapsible, clickable trees rather than static strings.

When to disable it (passObjectsNatively: false):

1. Log-time snapshots: Native mode is lazy; if an object mutates after the log call, DevTools shows the current state. Setting this to false renders the object to a string immediately, freezing its value at log time.
2. Text-matchable logs: DevTools filters and automated tools (like test runners) can only match the rendered string. They cannot see inside natively-passed objects.

new Logger({
  type: "pretty",
  pretty: {
    // on by default in browsers
    levelMethod: { WARN: console.warn, ERROR: console.error, FATAL: console.error },
  },
});

log.info("user loaded", { id: 42, roles: ["admin"] }); // object is collapsible in DevTools

Sub-loggers (created via getSubLogger() or the child() alias) allow you to create specialized loggers that inherit settings from a parent.

Key Features:

• Name Accumulation: Names are stored in _logMeta.parentNames, allowing you to trace the hierarchy (e.g., app -> db -> query).
• Bindings: Use bindings to attach static fields to every log record in the sub-logger. These fields merge down the chain and are masked according to your mask settings.
• Overriding: You can override the default logObj for a specific child by passing a second argument to getSubLogger().

const main = new Logger({ name: "app", bindings: { service: "checkout" } });
const db = main.getSubLogger({ name: "db" });

// Create a child with specific overrides
const query = db.child({ 
  name: "query", 
  minLevel: "DEBUG", 
  bindings: { pool: "primary" } 
});

query.info("slow query", { ms: 812 });
// Output includes: service: "checkout", pool: "primary", and parentNames: ["app", "db"]