LogTape 2.0.0: Dynamic logging and external configuration

[dahlia]

LogTape is a logging library for JavaScript and TypeScript that works across Deno, Node.js, Bun, and browsers. It's designed around structured logging with zero dependencies and flexible configuration—making it a solid foundation for both applications and libraries.

Version 2.0.0 marks a major release, introducing features that address some long-standing requests: dynamic context values, external configuration from JSON/YAML files, improved error handling, and async lazy evaluation. Here's what's new.

Dynamic context with lazy()

LogTape's with() method lets you attach context that gets included with every log from that logger. The problem is that with() captures values at the moment it's called—and child loggers inherit those captured values, not references to the original variables.

Consider this common pattern in SPAs:

let currentUser: User | null = null;

// Logger created before user data loads
const rootLogger = getLogger("app").with({ user: currentUser });
const featureLogger = rootLogger.getChild("feature");

// Later, user logs in
currentUser = await loadUser();

// But the context is still null—it was captured earlier
featureLogger.info("User action");  // user: null (not what we want!)

The new lazy() function solves this by deferring evaluation until logging time:

import { getLogger, lazy } from "@logtape/logtape";

let currentUser: User | null = null;

const rootLogger = getLogger("app").with({
  user: lazy(() => currentUser 
    ? { id: currentUser.id, isAdmin: currentUser.isAdmin } 
    : null
  )
});

const featureLogger = rootLogger.getChild("feature");

featureLogger.info("Before login");  // user: null

currentUser = await loadUser();
featureLogger.info("After login");   // user: { id: 1, isAdmin: true }

currentUser.isAdmin = false;
featureLogger.info("Role changed");  // user: { id: 1, isAdmin: false }

Child loggers inherit the lazy() wrapper itself, not its resolved value. Every time a log is written, the callback runs and captures the current state.

lazy() is also useful when you need to capture state at logging time:

const logger = getLogger("app").with({
  heapUsed: lazy(() => process.memoryUsage().heapUsed)
});

This records the actual memory usage at the moment each log is written.

See the lazy evaluation documentation for more details.

Configuration from JSON, YAML, or TOML

Until now, LogTape configuration required TypeScript code. The new @logtape/config package changes this by letting you load configuration from plain objects—which you can parse from JSON, YAML, TOML, or any other format.

import { configureFromObject } from "@logtape/config";
import { readFile } from "node:fs/promises";

const config = JSON.parse(await readFile("./logtape.json", "utf-8"));
await configureFromObject(config);

The configuration schema uses a module reference syntax for specifying sinks and formatters:

{
  "sinks": {
    "console": {
      "type": "#console()",
      "formatter": {
        "type": "#ansiColor()",
        "timestamp": "date-time-tz"
      }
    },
    "file": {
      "type": "@logtape/file#getFileSink()",
      "path": "/var/log/app.log",
      "formatter": "#jsonLines()"
    }
  },
  "loggers": [
    {
      "category": ["myapp"],
      "sinks": ["console", "file"],
      "lowestLevel": "info"
    }
  ]
}

Built-in shorthands like #console(), #ansiColor(), and #jsonLines() map to LogTape's core exports. You can also reference external packages directly with @logtape/file#getFileSink() or define custom shorthands.

Environment variable expansion is supported through the expandEnvVars() utility:

{
  "sinks": {
    "file": {
      "type": "@logtape/file#getFileSink()",
      "path": "${LOG_PATH:/var/log/app.log}"
    }
  }
}

For graceful error handling in production, set onInvalidConfig: "warn" to apply valid parts and log warnings rather than throwing errors.

Better error logging

Logging errors used to require wrapping them in properties:

// Before: verbose
logger.error("Request failed: {error.message}", { error });

Now you can pass Error objects directly to error(), warn(), and fatal():

// After: concise
logger.error(error);

The default message template is {error.message}, and the full error (including stack trace and cause chain) is available in properties. The JSON Lines formatter now properly serializes Error objects, preserving name, message, stack, cause, and errors (for AggregateError).

Async lazy evaluation

For operations that require await, logging methods now accept async callbacks:

await logger.debug("User activity", {
  userDetails: async () => await fetchUserDetails(userId)
});

The async function only executes if debug logging is enabled. If disabled, the returned Promise resolves immediately without calling the function.

Checking if a level is enabled

When you need to conditionally execute multiple log statements or expensive setup work, use the new isEnabledFor() method:

if (logger.isEnabledFor("debug")) {
  const snapshot = captureComplexState();
  const analysis = analyzeState(snapshot);
  
  logger.debug("State analysis: {report}", { report: generateReport(analysis) });
  logger.debug("Raw snapshot: {snapshot}", { snapshot });
}

Time-based log rotation

The @logtape/file package now supports time-based rotation alongside the existing size-based rotation:

import { getTimeRotatingFileSink } from "@logtape/file";

getTimeRotatingFileSink({
  directory: "./logs",
  interval: "daily",  // or "hourly", "weekly"
  maxAgeMs: 60 * 24 * 60 * 60 * 1000,  // Delete files older than 60 days
});

Files are automatically named with date patterns: 2025-01-15.log (daily), 2025-01-15-09.log (hourly), or 2025-W03.log (weekly).

New integrations

Elysia framework

The @logtape/elysia package provides HTTP request logging for Elysia applications:

import { elysiaLogger } from "@logtape/elysia";
import { Elysia } from "elysia";

const app = new Elysia()
  .use(elysiaLogger({ format: "combined" }));

Like the other framework integrations (Express, Fastify, Hono, Koa), it supports Morgan-compatible format presets, custom format functions, request filtering, and configurable log levels.

log4js adaptor

The @logtape/adaptor-log4js package allows LogTape to forward logs to existing log4js infrastructure:

import { getLog4jsSink } from "@logtape/adaptor-log4js";

getLog4jsSink({
  contextStrategy: "mdc",  // or "args"
  contextPreservation: "preserve"
});

This is useful when adopting LogTape-enabled libraries in applications already using log4js.

OpenTelemetry improvements

The @logtape/otel package received several updates:

Simplified attributes: Property keys are no longer prefixed with attributes., aligning with OpenTelemetry conventions. Existing queries referencing attributes.method should be updated to just method.

Error handling: The new exceptionAttributes option controls how Error objects are converted. The default "semconv" follows OpenTelemetry semantic conventions (exception.type, exception.message, exception.stacktrace). Set "raw" for the previous JSON serialization behavior.

Type preservation: Numbers and booleans are now preserved as their original types instead of being converted to strings.

Fingers crossed sink improvements

The bufferLevel option lets you separate which levels get buffered from which levels trigger the buffer flush:

fingersCrossed(consoleSink, {
  triggerLevel: "error",
  bufferLevel: "debug",  // Buffer debug and below; info/warn pass through immediately
});

Logs at info or warn pass through without buffering, while debug and trace logs are buffered until an error triggers the flush.

Windows Event Log improvements

The @logtape/windows-eventlog package now uses NELOG_OEM_Code (3299) from netmsg.dll for proper message formatting in Windows Event Viewer. A new formatter option allows custom text formatting.

Browser compatibility

The pagehide event replaces the deprecated unload event for automatic disposal in browser environments. This change improves compatibility with browser back/forward cache (bfcache) and mobile browsers.

Formatters

Text and JSON Lines formatters now support the lineEnding option for Windows compatibility ("crlf"). The ANSI color formatter gains "none" and "disabled" options for the timestamp field.

Breaking changes

@logtape/otel

Property keys no longer include the attributes. prefix. If you have queries or dashboards using attributes.method, update them to method.

Error objects now follow OpenTelemetry semantic conventions by default. Set exceptionAttributes: "raw" for the previous behavior.

@logtape/logtape

logger.warn(new Error(...)) and logger.fatal(new Error(...)) now produce slightly different output since these methods accept Error objects directly. Previously this was interpreted as the {*} shorthand.

Upgrading

Update your packages:

npm update @logtape/logtape
# or
deno add jsr:@logtape/logtape@^2.0.0

For the new packages:

npm install @logtape/config @logtape/elysia @logtape/adaptor-log4js

If you're upgrading from 1.x, check the breaking changes section above. The lazy() and configureFromObject() features are additive—existing configurations continue working.

See the full changelog for complete details.