fastify-xlogger

Standardized logging for Fastify v5 built on the built-in Pino logger. Register once to get automatic request context, secret redaction at the Pino level, canonical log schema, boundary logging for external API calls, and background job correlation.

Installation

npm install @xenterprises/fastify-xlogger

Quick Start

import Fastify from "fastify";
import xLogger, { getLoggerOptions } from "@xenterprises/fastify-xlogger";

const fastify = Fastify({
  logger: getLoggerOptions({ serviceName: "my-api" }),
});

await fastify.register(xLogger, { serviceName: "my-api" });

fastify.get("/users/:id", async (request) => {
  request.contextLog.info({ userId: request.params.id }, "Fetching user");

  fastify.xlogger.logEvent({
    event: "user.fetched",
    data: { userId: request.params.id },
    request,
  });

  return { id: request.params.id };
});

Options

request.contextLog

A Pino child logger automatically created for every request with canonical context fields:

fastify.get("/orders/:id", async (request) => {
  request.contextLog.info({ orderId: request.params.id }, "Processing order");
});

Methods

fastify.xlogger decorator

• logEvent — Log a structured business event with canonical schema.
• logBoundary — Log an external API call with vendor, operation, duration, and status.
• createBoundaryLogger — Create a timed boundary logger that captures duration automatically.
• createJobContext — Create a correlated child logger for background jobs with start, complete, and fail helpers.
• extractContext — Extract the canonical context object from a Fastify request.

Exported function

• getLoggerOptions — Build Pino logger options (redaction, serializers, transport) for use when creating the Fastify instance.

Default Redacted Paths

Auth headers: req.headers.authorization, req.headers.cookie, req.headers['set-cookie'], req.headers['x-api-key']

Secret fields: password, token, secret, apiKey, api_key, accessToken, access_token, refreshToken, refresh_token, privateKey, private_key

PII / payment: cardNumber, card_number, cvv, ssn, creditCard

Nested: *.password, *.token, *.secret, *.apiKey, *.api_key

Use redactPaths to extend, or redactClobber: true to replace entirely.

Error Reference

Startup Errors

Runtime Errors

Environment Variables

How It Works

On registration, the plugin validates all options and decorates fastify.xlogger with configuration and utility methods. An onRequest hook creates a Pino child logger (request.contextLog) for every request by calling extractContext — which reads request.user, standard headers (x-org-id, x-tenant-id, x-user-id), and the W3C traceparent header — and binding those fields to the child. An onResponse hook writes a canonical http.response event with status code, elapsed time, and request context; level is error for 5xx, warn for 4xx, info otherwise. The utility methods are stateless — they write to request.log when a request is provided, or to fastify.log otherwise. The exported getLoggerOptions() configures Pino's redaction, serializers, and transport at Fastify instantiation time.

AI Context

package: "@xenterprises/fastify-xlogger"
type: fastify-plugin
use-when: Structured logging with request context, secret redaction, boundary logging for external APIs, and background job correlation
decorator: fastify.xlogger (logEvent, logBoundary, createBoundaryLogger, createJobContext, extractContext)
request-decorator: request.contextLog — auto-created Pino child per request with requestId, userId, orgId, traceId
exported: getLoggerOptions() — call at Fastify instantiation with logger option
env: SERVICE_NAME, NODE_ENV, BETTERSTACK_SOURCE_TOKEN (all optional)