核心概念

配置

包含所有 evlog 配置选项的完整参考，包括全局 logger 设置、中间件选项、环境上下文以及框架特定的覆盖配置。

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

全局选项（`initLogger`）

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

src/index.ts

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

选项	类型	默认值	描述
`enabled`	`boolean`	`true`	全局启用/禁用日志记录。当为 `false` 时，所有操作都变为无操作
`env`	`Partial<EnvironmentContext>`	自动检测	环境上下文覆盖（详见下文）
`pretty`	`boolean`	开发环境下为 `true`	使用树形格式美化输出。根据 `NODE_ENV` 自动检测
`silent`	`boolean`	`false`	抑制控制台输出。事件仍会被构建、采样并传递给排水适配器
`stringify`	`boolean`	`true`	当 `pretty` 禁用时输出 JSON 字符串。在 Cloudflare Workers 中设置为 `false`
`minLevel`	`'debug' \| 'info' \| 'warn' \| 'error'`	`'debug'`	仅对全局 `log` API 生效的最低严重级别（不适用于 `createLogger` / 请求范围事件）。顺序：debug < info < warn < error
`sampling`	`SamplingConfig`	`undefined`	头部和尾部采样配置。参见采样
`redact`	`boolean \| RedactConfig`	在生产环境下为 `true`	默认在生产环境中启用。`false` 可禁用。对象用于细粒度控制。参见自动脱敏
`drain`	`(ctx: DrainContext) => void`	`undefined`	用于将事件发送到外部服务的排水回调

`minLevel` 与采样

minLevel 是一个 硬阈值，针对简单的 log.* API：低于阈值的级别永远不会被输出。它不适用于来自 useLogger / createLogger().emit() 的宽事件——应使用 sampling.rates（以及尾部 keep）来控制请求量。
头部采样（sampling.rates）是在已通过 minLevel 过滤的基础上进行的 概率性 采样。

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

环境上下文

env 选项控制每个日志事件中包含的字段。多数值会自动从环境变量和 package.json 中检测。

字段	类型	默认值	自动检测来源
`service`	`string`	`'app'`	`SERVICE_NAME`、`package.json` 名称
`environment`	`string`	`'development'`	`NODE_ENV`
`version`	`string`	`undefined`	`APP_VERSION`、`package.json` 版本
`commitHash`	`string`	`undefined`	`COMMIT_SHA`、`GIT_COMMIT`、`VERCEL_GIT_COMMIT_SHA`
`region`	`string`	`undefined`	`FLY_REGION`、`AWS_REGION`、`VERCEL_REGION`

静默模式

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

src/index.ts

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

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

如果启用 silent 但未配置排水适配器，事件会被构建和采样，但永远不会输出到任何地方。evlog 会在启动时对此发出警告。

中间件选项

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

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

选项	类型	默认值	描述
`include`	`string[]`	`undefined`	要记录的路由 glob 模式。未设置时记录所有路由
`exclude`	`string[]`	`undefined`	要排除的路由模式。排除优先于包含
`routes`	`Record<string, { service: string }>`	`undefined`	路由级服务名称覆盖
`drain`	`(ctx: DrainContext) => void`	`undefined`	每个事件发出时调用的排水回调
`enrich`	`(ctx: EnrichContext) => void`	`undefined`	发出后、排水前调用的增强回调
`keep`	`(ctx: TailSamplingContext) => void`	`undefined`	自定义尾部采样回调

Nuxt 和 Nitro 使用模块配置而非中间件选项。在 nuxt.config.ts 中通过 evlog 键配置所有全局和中间件选项，并通过 Nitro 钩子（evlog:drain、evlog:enrich、evlog:emit:keep）处理排水和增强。参考 Nuxt 配置与 Nitro 排水与增强器。

中间件排水与全局排水

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

src/index.ts

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 键下接受所有全局选项和中间件选项，并额外支持：

选项	类型	默认值	描述
`console`	`boolean`	`true`	启用/禁用浏览器控制台输出（仅客户端）
`transport.enabled`	`boolean`	`false`	通过 API 端点将客户端日志发送到服务器
`transport.endpoint`	`string`	`'/api/_evlog/ingest'`	自定义传输端点
`transport.credentials`	`RequestCredentials`	`'same-origin'`	请求凭据模式（`'include'` 用于跨域端点）

参见完整的 Nuxt 配置。

Nitro

Nitro 模块在 nitro.config.ts 中接受 enabled、env、pretty、silent、sampling、include、exclude 和 routes。排水和增强通过 Nitro 钩子完成。

参见 Nitro 排水与增强器。

Edit this pageorReport an issue

生命周期

了解 evlog 事件从创建到排干的完整生命周期。涵盖三种模式（简单日志、宽事件、请求日志）、采样、丰富化和传输。

采样

通过两级采样控制日志量。头部采样按级别丢弃噪声，尾部采样根据结果恢复关键事件。永远不会错过错误、慢请求或关键路径。