evlog 是一个用于 TypeScript 的结构化日志库。它提供简单的单行日志、在任意操作过程中累积上下文的广泛事件，以及解释 为什么 某事失败以及 如何 修复的结构化错误。
灵感来自 Logging Sucks（Boris Tane 著）。
哲学
传统日志记录已失效。你的日志分散在数十个文件中。每个请求生成超过 10 行日志。当出现问题时，你只能通过 grep 在噪音中寻找信号。
evlog 采用了不同的方法：
结构化日志
用类型化、结构化的事件替换
console.log，这些事件通过排水管道流动。广泛事件
在任意工作单元（请求、脚本或作业）过程中累积上下文并只发出一次。
结构化错误
解释为什么发生以及如何修复的错误。
对开发者友好
开发阶段人类可读，生产环境为可解析的 JSON。
三种记录方式
evlog 为不同上下文提供三种 API。你可以在同一个项目中使用所有三种方式。
简单日志
即发即忘的结构化日志。替换 console.log、consola 或 pino：
src/index.ts
import { log } from 'evlog'
log.info('auth', '用户已登录')
log.error({ action: 'payment', error: 'card_declined', userId: 42 })
广泛事件
在任意操作过程中逐步累积上下文，然后发出一个全面的事件：
import { createLogger } from 'evlog'
const log = createLogger({ jobId: 'sync-001', queue: 'emails' })
log.set({ batch: { size: 50, processed: 50 } })
log.emit()
import { createRequestLogger } from 'evlog'
const log = createRequestLogger({ method: 'POST', path: '/api/checkout' })
log.set({ user: { id: 1, plan: 'pro' } })
log.emit()
import { useLogger } from 'evlog'
export default defineEventHandler(async (event) => {
const log = useLogger(event)
log.set({ user: { id: 1, plan: 'pro' } })
return { success: true }
// 在响应结束时自动发出
})
一个日志，包含所有上下文。理解发生的一切所需的一切都包含其中。
结构化错误
带有可操作上下文的错误：why 它发生，如何 fix，以及指向文档的 link：
import { createError } from 'evlog'
throw createError({
message: 'Payment failed',
status: 402,
why: 'Card declined by issuer (insufficient funds)',
fix: 'Try a different payment method or contact your bank',
link: 'https://docs.example.com/payments/declined',
})
{
"statusCode": 402,
"message": "Payment failed",
"data": {
"why": "Card declined by issuer (insufficient funds)",
"fix": "Try a different payment method or contact your bank",
"link": "https://docs.example.com/payments/declined"
}
}
为什么上下文很重要
我们正在进入一个 AI 代理构建、调试和维护应用程序的时代。这些代理需要 结构化上下文 才能有效工作：
why：根本原因，让代理理解哪里出了问题fix：可操作的解决方案，供代理建议或应用link：复杂问题的文档
传统的 console.log 和通用的 throw new Error() 无法提供可操作的上下文。evlog 的结构化输出旨在供人类和 AI 解析并采取行动。