配置

evlog 有两个配置面，本页面将分别介绍：启动时设置一次的全局选项，以及按框架集成分别设置的中间件选项。

全局选项（initLogger）

这些选项适用于所有框架。对于独立框架（Hono、Express、Fastify、Elysia、NestJS、SvelteKit、Cloudflare Workers），在应用启动时调用一次 initLogger()。对于 Nuxt 和 Nitro，这些选项通过模块配置设置并自动传递。

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 字段（当 redact 为对象时）：paths（带通配符的点号表示法）、patterns（针对字符串值的正则表达式）、builtins、replacement（字符串，或根据匹配值计算替换内容的函数）、transform（用于条件策略的钩子）。完整表格请参见自动脱敏。

minLevel 与采样的区别

• minLevel 是简单 log.* API 上的硬阈值：低于该阈值的级别永远不会输出。它不适用于来自 useLogger / createLogger().emit() 的宽事件，请使用 sampling.rates（以及尾部采样的 keep）控制请求量
• 头部采样（sampling.rates）针对简单日志中已经通过 minLevel 的内容进行概率采样

对 log.info / log.debug / 等调用的求值顺序为：enabled → minLevel → 头部采样 → 输出。

调整开发终端输出

美化错误块仅在 pretty: true 时运行（开发环境中的默认值）。生产环境始终输出 JSON 宽事件，不包含堆栈片段，也不会读取磁盘。

使用 dev 来控制两个相互独立的轴：Nitro 的 Youch 覆盖层是否运行，以及 evlog 在宽事件中打印多少堆栈细节。

预设（推荐）：

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

显式对象（细粒度）：

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

请参见 Structured Errors 中的开发终端输出，了解美化错误树的示例。

在每个事件中标记环境

env 选项控制每个日志事件中包含的字段。下表列出了未设置字段时读取各字段的变量。

静默终端

当部署平台以标准输出为主要日志采集方式（GCP Cloud Run、AWS Lambda、Fly.io、Railway 等），且你希望由排水适配器控制输出格式时，请使用 silent。

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

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

中间件选项

这些选项传递给框架中间件/插件，用于控制每个请求的行为：包括记录哪些路由、如何排水和丰富事件，以及自定义尾部采样逻辑。

// 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(),
})

中间件排水与全局排水

当设置了中间件 drain 时，它会覆盖来自 initLogger() 的全局排水适配器。如果未设置中间件排水，则使用全局排水作为回退，并可获得完整的增强事件（含请求上下文，如方法、路径、头部）。

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

initLogger({
  env: { service: 'my-api' },
  drain: createAxiomDrain(), // 回退：被单例 log API 和无中间件排水时使用
})

app.use(evlog({
  // 未设置排水——回退到全局排水，并携带完整请求上下文
}))

特定框架选项

某些框架拥有超出共享配置的额外选项：

Nuxt

Nuxt 模块在 nuxt.config.ts 的 evlog 键下接受所有全局选项和中间件选项，并额外支持：

查看完整的 Nuxt 配置。

Nitro

Nitro 模块在 nitro.config.ts 中接受 enabled、env、pretty、silent、sampling、include、exclude 和 routes，而排水和增强则交由 Nitro 钩子处理。

查看 Nitro 排水与增强器。