@beignet/provider-logger-pino

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

[!CAUTION] Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

Pino-backed LoggerPort provider for Beignet.

Use this package when you want ctx.ports.logger backed by Pino while keeping application code dependent on the stable LoggerPort interface from @beignet/core/ports.

createPinoLoggerProvider(...) returns the stable PinoLoggerProvider type. LoggerPinoConfig describes its validated config; the Zod schema remains internal.

Install

bun add @beignet/core @beignet/provider-logger-pino pino

Pretty development logs are optional:

bun add -d pino-pretty

Setup

The Beignet starter already registers createPinoLoggerProvider() in server/providers.ts. Configure that entry while preserving the other providers and the existing server context:

// server/providers.ts (Pino entry excerpt)
createPinoLoggerProvider({ level: "info", format: "json", service: "api" }),

The factory is imported from @beignet/provider-logger-pino. In a manually assembled app, add that import and register one instance in the existing provider list. See the logging guide for a complete Todos use case and verification steps.

The provider installs ctx.ports.logger. It flushes the provider-owned Pino logger during server.stop() so buffered destinations can drain before shutdown, and closes the worker-backed pretty transport when Beignet created it. Every structured metadata object and child binding passes through Beignet's default recursive credential redaction before it reaches Pino.

beignet doctor --strict checks that installed Pino logger providers are registered in server/providers.ts.

Environment

The provider reads LOG_-prefixed environment variables:

LOG_FORMAT=pretty requires pino-pretty. If it is unavailable, the provider falls back to JSON logging and emits a warning.

Use createPinoLoggerProvider(...) when you want to pass options directly instead of relying only on LOG_* env vars. Options override env-derived values:

import { createPinoLoggerProvider } from "@beignet/provider-logger-pino";

// Replace the existing provider call with these options.
const loggerProvider = createPinoLoggerProvider({
  level: "debug",
  format: "pretty",
  service: "api",
  timestamp: true,
});

Direct adapter

Use createPinoLogger(...) when the app owns Pino configuration, transports, or destinations:

import { createPinoLogger } from "@beignet/provider-logger-pino";
import pino from "pino";

const destination = pino.destination("./app.log");
const pinoLogger = pino({ level: "info" }, destination);
const logger = createPinoLogger({ logger: pinoLogger });

The direct factory only adapts the supplied Pino logger to LoggerPort; the caller owns flushing and destination shutdown. It applies the same default metadata and child-binding redaction as the lifecycle provider.

Usage

ctx.ports.logger.info("Post published", {
  postId: post.id,
  actorId: ctx.actor.type === "user" ? ctx.actor.id : undefined,
});

const log = ctx.ports.logger.child({ requestId: ctx.requestId });
log.error("Failed to publish post", { error });

Exports

Installed ports

The provider contributes ctx.ports.logger, the standard Beignet LoggerPort. Use createPinoLogger(...) when app infrastructure needs to own the underlying Pino logger; application workflows should continue to depend on the stable port.

Instrumentation

This provider does not record devtools provider events for each log call. Logs are the primary output. Use provider instrumentation on the external providers doing work, and include requestId, traceId, actor, tenant, or feature metadata in log bindings when those fields are useful operational context.

Failure behavior

Invalid LOG_* configuration fails during provider setup. If LOG_FORMAT=pretty is configured without pino-pretty, the provider falls back to JSON logging and emits a warning instead of failing startup. A provider-owned logger flush or transport-close failure is surfaced from server.stop() as a provider shutdown error.

Local and tests

Use LOG_FORMAT=pretty for local development when pino-pretty is installed. Use a memory or fake LoggerPort in use-case tests when assertions should not depend on console output.

Deployment notes

Use JSON logs in production unless the runtime explicitly expects formatted text. Set LOG_SERVICE per deployed service and include request/trace metadata from Beignet context so logs correlate with devtools, provider events, and error reports.

Default redaction covers sensitive structured keys such as tokens, passwords, cookies, authorization headers, sessions, and credentials, including nested objects and child bindings. Log messages are not rewritten, so never interpolate secrets into the message string. Use redactValue(...) before building a message or when app-specific fields need stricter redaction.

Read next

• Docs site logging guide: https://beignetjs.com/logging
• Providers: https://beignetjs.com/providers
• Pino documentation: https://getpino.io/

License

MIT