LogTape 2.3.0: Scoped configuration, failure-only test logs, and GraphQL Yoga

[dahlia]

LogTape is a logging library for JavaScript and TypeScript that works across Deno, Node.js, Bun, and browsers. It's built around structured logging, has zero dependencies, and is designed to work as well in library code as in application code.

Version 2.3.0 adds scoped configuration for temporary logging policies, a failure log reporter with dedicated packages for four test runners, a GraphQL Yoga integration, and finer control over what the Sentry sink reports. Here's what changed.

Scoped configuration

configure() sets logging policy for the whole process, which fits an application entry point but is awkward for temporary behavior inside one execution flow. A test helper that wants a buffering sink for one test case, or a request handler that wants verbose output for one request, previously had no way to do that without mutating the same global logger tree every other concurrent test or request also depends on.

The new withConfig() installs a ScopedConfig for the duration of a callback, reusing the contextLocalStorage you already pass to configure():

import { AsyncLocalStorage } from "node:async_hooks";
import { configure, getConsoleSink, getLogger, withConfig } from "@logtape/logtape";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [{ category: "my-app", lowestLevel: "info", sinks: ["console"] }],
  contextLocalStorage: new AsyncLocalStorage(),
});

await withConfig({
  sinks: { debug: getConsoleSink() },
  loggers: [{ category: "my-app", lowestLevel: "debug", sinks: ["debug"] }],
}, async () => {
  getLogger("my-app").debug("Only visible inside this scope.");
});

getLogger("my-app").debug("Back to the process-wide configuration.");

The scoped configuration is a full override, not a merge: sinks and filters from the process-wide configuration aren't inherited, so a scope that wants meta logs configures them itself. Nested withConfig() calls restore the outer scope on exit, and sinks or filters created for a scope are disposed once its callback settles. withConfig() requires Config.contextLocalStorage to already be set; without it, it throws a ConfigError rather than falling back silently. withConfigSync() is the synchronous counterpart, and it rejects callbacks that return a promise.

See the scoped configuration documentation for the full lifetime and nesting rules. (#185, #188)

Failure log reporter

@logtape/testing now ships createFailureLogReporter(). It buffers log records while a wrapped callback runs, discards them if the callback passes, and reports them to a sink if it throws or rejects, so a passing test suite stays quiet while a failing one still shows what led up to the failure:

import { createFailureLogReporter } from "@logtape/testing/reporter";

const reporter = createFailureLogReporter({ lowestLevel: "debug" });

test("saves a draft", reporter.wrap(async () => {
  // Logs emitted here are reported only if this callback fails.
}));

The reporter is built on scoped configuration, so it doesn't call configure() or reset() around each test and doesn't touch process-wide routing while a test runs; it still requires the process-wide configuration to provide Config.contextLocalStorage. wrap() preserves whatever parameters the test runner passes to the callback (a test context, fixtures) and always returns an async function. run() invokes the callback directly for callers that don't go through a test runner's wrap()-style API.

The default mode is on-failure. Set mode: "always" to see buffered logs even for passing tests, or mode: "never" to keep a shared wrapper in place while suppressing output. sink and formatter customize where and how reports are written, and getFailureLogReporterOptionsFromEnv() parses LOGTAPE_TEST_MODE and LOGTAPE_TEST_LOWEST_LEVEL through a runtime-specific environment reader. The recorder API now also has its own @logtape/testing/recorder entry point alongside the new @logtape/testing/reporter; the root @logtape/testing export still re-exports both for compatibility. (#186, #190)

Runner-aware testing packages

Wrapping every test callback with reporter.wrap() by hand works, but it's tedious across a large suite. Four new packages adapt the reporter to the runner you're already using: @logtape/testing-node, @logtape/testing-deno, @logtape/testing-bun, and @logtape/testing-vitest.

Each package exports a wrapped test (and, where the runner has one, it) that behaves like the runner's own. The Node.js integration, for example:

import { test } from "@logtape/testing-node/autoload";
import { getLogger } from "@logtape/logtape";

test("case", async () => {
  getLogger(["my-lib"]).info("Fixture state: {state}.", { state: "ready" });
  // The info log is printed only if this test fails.
});

The autoload entry point configures the minimal contextLocalStorage the reporter needs when LogTape hasn't been configured yet. If your suite already configures LogTape, that configuration must include contextLocalStorage, or autoload throws instead of silently overriding it. Each package also exports createTest() (and @logtape/testing-vitest a createVitest()) for setting lowestLevel, mode, sink, or formatter explicitly.

Runner-specific features carry through unchanged: test.only(), test.skip(), and test.todo() on Node.js; test.each() and wrapped TestContext.step() on Deno; Bun's shorthand helpers and callback-style tests; and Vitest's test.each(), test.for(), test.extend(), and fixture callbacks. (#187, #191)

New package: @logtape/graphql-yoga

@logtape/graphql-yoga is a new package that lets GraphQL Yoga use LogTape as its logging backend through Yoga's createYoga({ logging }) option:

import { configure, getConsoleSink } from "@logtape/logtape";
import { getYogaLogger } from "@logtape/graphql-yoga";
import { createSchema, createYoga } from "graphql-yoga";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: ["graphql-yoga"], sinks: ["console"], lowestLevel: "debug" },
  ],
});

const yoga = createYoga({
  schema: createSchema({ /* ... */ }),
  logging: getYogaLogger(),
});

Yoga's logger methods take arbitrary arguments; the adapter treats a leading string as the message, a leading plain object as structured properties, and a leading Error as LogTape's error-aware logging path, keeping any remaining arguments under an args property instead of flattening or stringifying them. The default level mapping (debug to debug, info to info, warn to warning, error to error) can be overridden with YogaLoggerOptions.levelsMap. (#184)

@logtape/sentry: Error properties and level routing

The Sentry sink decides whether to call captureException() by checking an error or, failing that, a Pino-style err property for an Error value. The new errorPropertyNames option on SentrySinkOptions lets you replace that list for logging conventions that use a different property name; the default remains ["error", "err"]. Thanks to @matthiasfeist for the issue report that started this. (#189)

Until now, the sink also had only one filter point ahead of every output path, so there was no way to keep verbose records as breadcrumbs while sending only warning and above through Sentry's Logs API: withFilter() drops records before the sink ever sees them, so they never become breadcrumbs either. The new logs and breadcrumbs options route by level after the sink has accepted a record:

import * as Sentry from "@sentry/node";
import { configure } from "@logtape/logtape";
import { getSentrySink } from "@logtape/sentry";

Sentry.init({ dsn: process.env.SENTRY_DSN, enableLogs: true });

await configure({
  sinks: {
    sentry: getSentrySink({
      logs: { level: "warning" },
      breadcrumbs: { maxLevel: "info" },
    }),
  },
  loggers: [{ category: [], sinks: ["sentry"], lowestLevel: "trace" }],
});

With this configuration, trace, debug, and info records become breadcrumbs, while warning, error, and fatal records are also sent through Sentry's Logs API; error and fatal records still create Sentry Issues as before, independent of this routing. breadcrumbs: true takes over what enableBreadcrumbs: true used to do; enableBreadcrumbs still works but is deprecated. beforeSend is unchanged and still applies to every output path ahead of this routing. Thanks to @sebws for reporting the gap and sketching the shape of the fix. (#193, #194)

Agent skill: install straight from the repository

The LogTape Agent Skill has been available through the @logtape/logtape npm package since 2.1.0. It can now also be installed directly from this repository with npx skills add dahlia/logtape, and the repository can be added as a Claude Code plugin marketplace for teams that manage skills that way.

Upgrading

npm update @logtape/logtape

# if you use the testing utilities package
npm update @logtape/testing

# new runner-specific testing packages
npm install --save-dev @logtape/testing-node
npm install --save-dev @logtape/testing-bun
npm install --save-dev @logtape/testing-vitest

# new Deno test runner package (JSR only)
deno add --dev jsr:@logtape/testing-deno

# new GraphQL Yoga integration
npm install @logtape/graphql-yoga

# if you use the Sentry integration
npm update @logtape/sentry

There are no breaking changes in 2.3.0. See the full changelog for complete details.