Configuration

evlog has two configuration surfaces, and this page documents both: global options set once at startup, and middleware options set per framework integration.

Global options (initLogger)

These options apply to all frameworks. Call initLogger() once at application startup for standalone frameworks (Hono, Express, Fastify, Elysia, NestJS, SvelteKit, Cloudflare Workers). For Nuxt and Nitro, these are set via module config and passed through automatically.

import { initLogger } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'

initLogger({
  enabled: true,
  env: { service: 'my-api', environment: 'production' },
  pretty: false,
  silent: false,
  stringify: true,
  minLevel: 'info',
  sampling: { rates: { info: 10 }, keep: [{ status: 400 }] },
  drain: createAxiomDrain(),
})

RedactConfig fields (when redact is an object): paths (dot-notation with globs), patterns (regex on string values), builtins, replacement (string, or a function computing it from the matched value), transform (hook for conditional policies). Full table in Auto-Redaction.

minLevel vs sampling

• minLevel is a hard threshold on the simple log.* API: levels below the threshold are never emitted. It does not apply to wide events from useLogger / createLogger().emit(), use sampling.rates (and tail keep) for request volume.
• Head sampling (sampling.rates) is probabilistic on what is already allowed by minLevel for simple logs.

Evaluation order for log.info / log.debug / etc.: enabled → minLevel → head sampling → output.

Tune the dev terminal output

Pretty error blocks run only when pretty: true (default in development). Production always emits JSON wide events, with no stack snippets and no disk reads.

Use dev to control two independent axes: whether Nitro's Youch overlay runs, and how much stack detail evlog prints inside the wide event.

Presets (recommended):

export default defineNuxtConfig({
  modules: ['evlog/nuxt'],
  evlog: {
    pretty: true,
    dev: 'evlog', // or 'nitro' | 'both'
  },
})

Explicit object (fine-grained):

evlog: {
  dev: {
    frameworkOverlay: true,
    prettyError: {
      snippet: false,
      stackDepth: 0,
      compact: true,
      detail: 'guidance', // 'full' | 'guidance'
    },
  },
}

See Development terminal output in Structured Errors for an example of the pretty error tree.

Stamp the environment on every event

The env option controls the fields included in every log event, and the table below names the variable each one is read from when you leave it unset.

Silence the terminal

Use silent when your deployment platform captures stdout as its primary log ingestion (GCP Cloud Run, AWS Lambda, Fly.io, Railway, etc.) and you want a drain adapter to control the output format.

import { initLogger } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'

initLogger({
  silent: process.env.NODE_ENV === 'production',
  drain: createAxiomDrain(),
})

Middleware options

These options are passed to the framework middleware/plugin. They control per-request behavior: which routes to log, how to drain and enrich events, and custom tail sampling logic.

// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createAxiomDrain } from 'evlog/axiom'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  include: ['/api/**'],
  exclude: ['/api/health'],
  routes: { '/api/auth/**': { service: 'auth' } },
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
  keep: (ctx) => { if (ctx.duration > 2000) ctx.shouldKeep = true },
})

app.use(evlog({
  include: ['/api/**'],
  exclude: ['/api/health'],
  routes: { '/api/auth/**': { service: 'auth' } },
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
  keep: (ctx) => { if (ctx.duration > 2000) ctx.shouldKeep = true },
}))

app.use(evlog({
  include: ['/api/**'],
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
}))

await app.register(evlog, {
  include: ['/api/**'],
  drain: createAxiomDrain(),
})

Middleware drain vs global drain

When a middleware drain is set, it takes precedence over the global drain from initLogger(). If no middleware drain is set, the global drain is used as fallback, with the benefit of receiving the full enriched event with request context (method, path, headers).

import { initLogger } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'

initLogger({
  env: { service: 'my-api' },
  drain: createAxiomDrain(), // fallback: used by singleton log API AND middleware (if no middleware drain)
})

app.use(evlog({
  // no drain here - falls back to globalDrain from initLogger, with full request context
}))

Framework-specific options

Some frameworks have additional options beyond the shared config:

Nuxt

The Nuxt module accepts all global options and middleware options in nuxt.config.ts under the evlog key, plus:

See the full Nuxt configuration.

Nitro

The Nitro module accepts enabled, env, pretty, silent, sampling, include, exclude, and routes in nitro.config.ts, and leaves drain and enrichment to the Nitro hooks.

See Nitro drain & enrichers.