@logbrew/fastify

Fastify plugin helpers for the public LogBrew JavaScript SDK.

This package is intentionally thin. It adds Fastify request lifecycle UX while keeping event validation, retry, flush, and shutdown behavior in @logbrew/sdk.

Install

npm install @logbrew/sdk @logbrew/fastify fastify
pnpm add @logbrew/sdk @logbrew/fastify fastify

Request Plugin

import Fastify from "fastify";
import { RecordingTransport } from "@logbrew/sdk";
import { logbrewFastifyPlugin } from "@logbrew/fastify";

const app = Fastify();

await app.register(logbrewFastifyPlugin, {
  serverApiKey: "LOGBREW_SERVER_API_KEY",
  transport: RecordingTransport.alwaysAccept()
});

app.get("/health", async (request) => {
  request.logbrew.client.log("evt_log_001", "2026-06-02T10:00:03Z", {
    message: "health check reached",
    level: "info",
    logger: "fastify"
  });
  return { ok: true };
});

Use serverApiKey directly for local server examples, or set LOGBREW_SERVER_API_KEY in your server environment and omit it. apiKey and LOGBREW_API_KEY are still accepted for compatibility with the lower-level JavaScript SDK. Automatic request and error metadata records the path without query text by default.

When an incoming request has a valid W3C traceparent header, the default request capture records the request as a LogBrew span that continues the incoming trace. Requests without traceparent, or with a malformed header, fall back to the existing request log event so bad client headers do not break your app. Use spanIdFactory when tests or edge runtimes need deterministic child span IDs:

await app.register(logbrewFastifyPlugin, {
  serverApiKey: "LOGBREW_SERVER_API_KEY",
  spanIdFactory: () => "b7ad6b7169203331",
  transport: RecordingTransport.alwaysAccept()
});

Error Capture

import { logbrewFastifyPlugin } from "@logbrew/fastify";

await app.register(logbrewFastifyPlugin, {
  serverApiKey: "LOGBREW_SERVER_API_KEY"
});

app.get("/fail", async () => {
  throw new Error("route exploded");
});

app.setErrorHandler((error, _request, reply) => {
  reply.code(500).send({ error: error.message });
});

The plugin uses Fastify's onRequest, onResponse, and onError hooks. onResponse runs after the response has been sent, which makes it a good place to flush request telemetry without changing the response body; onError captures thrown route errors before your normal error response handler finishes the request.

Packaged Examples

After install, these commands are available from a consumer app:

node node_modules/@logbrew/fastify/examples/index.mjs --help
node node_modules/@logbrew/fastify/examples/index.mjs --list
node node_modules/@logbrew/fastify/examples/index.mjs readme-example
node node_modules/@logbrew/fastify/examples/index.mjs real-user-smoke
node node_modules/@logbrew/fastify/examples/index.mjs
npm --prefix node_modules/@logbrew/fastify/examples run help
npm --prefix node_modules/@logbrew/fastify/examples run list
npm --prefix node_modules/@logbrew/fastify/examples run readme-example
npm --prefix node_modules/@logbrew/fastify/examples run real-user-smoke

The default launcher path runs real-user-smoke.