Logger

HTTP requests leave no trace by default. When a production issue hits, you need structured logs with correlation IDs to track requests across services and find the failure point.

The logger middleware solves this: structured request/response logging, automatic correlation ID tracking, and a request-scoped logger attached to every context as ctx.log.

Default Behavior

With default options, logger():

• Logs request completion with method, path, status code, and duration
• Generates a UUID correlation ID per request (via crypto.randomUUID())
• Sets the correlation ID in the x-request-id response header
• Attaches a scoped logger to ctx.log with the correlation ID
• Logs request start in development only (based on isProductionBuild())
• Uses info level for 2xx/3xx, warn for 4xx, error for 5xx responses

Installation

$ pnpm add @nextrush/logger

This package wraps @nextrush/log and re-exports all its functionality.

Minimal Usage

import { createApp } from '@nextrush/core';
import { logger } from '@nextrush/logger';

const app = createApp();

app.use(logger());

app.use(async (ctx) => {
  ctx.log.info('Processing request');
  ctx.json({ ok: true });
});

The middleware attaches ctx.log — a request-scoped logger that includes the correlation ID in every log entry.

Configuration Options

LoggerMiddlewareOptions controls the middleware behavior. It extends LoggerOptions from @nextrush/log.

app.use(
  logger({
    minLevel: 'info',
    skip: (ctx) => ctx.path === '/health',
    logRequestStart: false,
    correlationIdHeader: 'x-request-id',
    context: 'api',
  })
);

Programmatic API (re-exported from @nextrush/log)

Beyond the middleware surface above, this package re-exports its entire underlying @nextrush/log library — useful for application code that needs structured logging outside a request (startup, background jobs, CLI scripts).

Integration Example

Correlation IDs Across Services

Track requests through microservices using the correlation ID:

import { logger } from '@nextrush/logger';
import type { LoggerContext } from '@nextrush/logger';

app.use(logger());

app.use(async (ctx) => {
  const correlationId = (ctx as LoggerContext).log.getCorrelationId();

  const response = await fetch('https://api.internal/data', {
    headers: { 'x-request-id': correlationId ?? '' },
  });

  ctx.json(await response.json());
});

Logger Without Request Logging

Use attachLogger() when you need ctx.log but not automatic request/response logging:

import { attachLogger } from '@nextrush/logger';

app.use(attachLogger({ context: 'api' }));

app.use(async (ctx) => {
  ctx.log.info('Handler called');
  ctx.json({ ok: true });
});

Type Guards

import { hasLogger, getLogger } from '@nextrush/logger';

app.use(async (ctx) => {
  if (hasLogger(ctx)) {
    ctx.log.info('Logger available');
  }

  // Get logger with automatic fallback
  const log = getLogger(ctx, 'fallback-context');
  log.info('Works with or without middleware');
});

Standalone Logger

Create loggers outside of middleware context:

import { createLogger } from '@nextrush/logger';

const log = createLogger('MyService');
log.info('Server starting');
log.error('Connection failed', new Error('timeout'));

Compatibility

@nextrush/core is an optional peer dependency — only needed for the Middleware/Context types it references at compile time; the middleware itself only needs a NextRush-shaped Context.

Common Mistakes

Placing logger middleware after route handlers. The middleware must run before handlers to attach ctx.log. Register it early in the middleware chain.

Skipping health checks without the skip option. Health check endpoints generate high-volume logs with no diagnostic value. Use skip: (ctx) => ctx.path === '/health'.

Using redactKeys instead of sensitiveKeys. The option inherited from @nextrush/log is sensitiveKeys, not redactKeys.

Troubleshooting

ctx.log is undefined — The logger middleware did not run before your handler. Ensure app.use(logger()) is registered before route handlers. If using skip, verify your route is not being skipped.

Correlation ID not appearing in logs — Set generateCorrelationId: true (the default). If using a custom header name, ensure correlationIdHeader matches the header your upstream service sends.

Too many logs in production — Set minLevel: 'info' and logRequestStart: false to reduce volume. Use skip to exclude health checks and static asset paths.

Related

• Reference — All packages
• @nextrush/request-id — Request ID middleware
• @nextrush/timer — Response timing