evlog

evlog

当工作涉及 evlog 时使用此技能——宽事件、结构化错误、排出目标、采样、审计跟踪、AI SDK / eve 遥测、CLI 产品遥测、客户端日志记录、插件，或 @evlog/cli map 覆盖率评分。

快照：[email protected]、@evlog/[email protected]、@evlog/[email protected]（已于 2026-10-01 验证；没有更新的版本）。如果版本不同，请根据 source-map.md 更新。

工作流

1. 修改代码前，检查本地日志记录情况：
   • 正在使用的 evlog、可选的 @evlog/cli / @evlog/telemetry / @evlog/nuxthub、框架对等依赖和排出目标的包版本。
   • 集成路径：Nuxt/Nitro 模块、Next createEvlog/withEvlog、TanStack Start evlog/nitro/v3、Hono/Express/Fastify/Elysia 中间件、Workers、Astro/Lambda 指南、独立的 initLogger。
   • 模式：分散的 console/pino 日志行与 log.set 宽事件、createError({ why, fix })、审计、AI 封装、eve 钩子、客户端采集、插件。
2. 版本或 API 不明确时，更新文档。从 source-map.md 开始。
3. 安装、三种日志记录模式、initLogger 和核心 API，请参阅 setup-core.md。
4. 宽事件设计、封存/fork、结构化错误、目录和脱敏，请参阅 wide-events-errors.md。
5. 框架接线和适配器选择，请参阅 frameworks-adapters.md。
6. 管道、采样、审计、AI、客户端日志和 evlog map/CI，请参阅 cli-advanced.md。
7. 插件、流、诊断、工具包、@evlog/telemetry 和 evlog/eve，请参阅 extend.md。

实现判断

• 优先选择每个工作单元一个宽事件（先调用 log.set，再自动 emit 或手动 emit），而不是在同一个请求/作业/轮次中记录多条 info 日志。
• 将上下文归入带有明确键名的嵌套对象（user、cart、payment），而不是堆砌扁平的 userId/cartId 或使用通用的 data 容器。
• 使用合适的模式：一次性操作使用 log.*；自行管理生命周期时使用 createLogger / createRequestLogger；由框架管理创建和 emit 时使用框架的 useLogger / req.log / c.get('log')。
• 在 pretty 模式下，带标签的 log.info('tag', 'message') 只会输出到控制台。对象形式始终会发送到排出目标。
• 使用 createError({ message, status, why, fix, link?, code?, internal? }) 抛出错误，而不是直接抛出 Error。在客户端使用 parseError 解析。
• emit 后（或采样丢弃后），日志记录器会被封存——响应完成后调用 set 会被忽略。需要有意创建后台子事件时，请使用 log.fork（若可用）。
• 库和共享包：使用 createLogger / 接受一个日志记录器；不要调用 initLogger 并强制宿主接入排出目标。
• 生产环境：使用 createDrainPipeline（批处理 + 重试）包装适配器；启用头部和尾部采样；保留错误以及资金/身份验证路径的日志。
• 对 Nuxt/Nitro/Next/TanStack Start/Hono，在进行大型日志重构前运行 bunx @evlog/cli map——先修复 FIX FIRST。请在 CI 中固定 CLI 版本。

验证

优先使用仓库现有的检查。对于有实质影响的 evlog 改动，请纳入相关检查：

• 在本地访问一个路由/作业，并确认产生一个包含预期嵌套字段的宽事件（开发环境中使用 pretty 模式）。
• 触发 createError 路径，并确认日志中的 why/fix 以及客户端的 parseError。
• 修改入口覆盖率或设置时，运行 bunx @evlog/cli map / doctor。
• 修改管道时进行排出目标冒烟测试（Axiom/Sentry/Loki/fs NDJSON）；关闭时刷新缓冲区。
• 检查采样配置：在接近生产环境的配置中，错误和 keep 规则仍会保留。
• 对 RequestLogger、类型化字段和目录导入执行类型检查。