fastify-xlogger
Fastify plugin for standardized logging with Pino — context, redaction, and canonical schema.
fastify-xlogger
Standardized logging with Pino. Provides automatic request context, secret redaction, canonical log schema, boundary logging for external APIs, 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',
})
Configuration
await fastify.register(xLogger, {
serviceName: 'my-api', // Required: service identifier
redact: ['password', 'token'], // Additional fields to redact
level: 'info', // Log level override
})
Options
| Option | Type | Default | Description |
|---|---|---|---|
serviceName | string | required | Service name for all log entries |
redact | string[] | [] | Additional fields to redact |
level | string | 'info' | Minimum log level |
Decorators
fastify.xlogger
fastify.xlogger.logEvent({
event: 'user.created',
data: { userId: '123' },
request,
})
fastify.xlogger.logBoundary({
service: 'stripe',
operation: 'createCustomer',
data: { email },
})
request.contextLog
Automatically includes request ID, user ID, and trace context:
fastify.get('/users/:id', async (request) => {
request.contextLog.info({ userId: request.params.id }, 'Fetching user')
// Logs: { service: 'my-api', requestId: '...', userId: '...', msg: 'Fetching user' }
})
Philosophy
- Use Fastify's built-in Pino as the single logging engine
- Never create a second logger
- Log structured objects, not concatenated strings
- Automatically redact secrets at the logger level
- Standardize context across all log entries
AI Context
package: "@xenterprises/fastify-xlogger"
type: fastify-plugin
decorates: [fastify.xlogger, request.contextLog]
use-when: All Fastify APIs — register once, use everywhere
critical: Register BEFORE other plugins so contextLog is available
request.contextLog: auto-includes requestId, userId from JWT, traceparent
fastify.xlogger.logBoundary: use when calling external APIs (Stripe, SendGrid, etc.)
fastify.xlogger.logEvent: use for business events (user.created, payment.processed)