入门

介绍

快速开始 GitHub

通过 evlog 了解你的应用中发生了什么：结构化日志、广泛事件，以及能够解释问题原因和修复方法的错误。

evlog 是一个 TypeScript 日志记录库，帮助你了解应用中发生了什么。从结构化日志开始，将一个请求的上下文汇总到一个广泛事件中，并将失败转化为能够解释问题原因和修复方法的错误。

在下一个项目中使用它，或将它与现有日志记录器结合使用。快速开始可以帮助你快速上手；迁移示例展示了如何将熟悉的日志记录模式引入 evlog。

灵感来自 Boris Tane 的 Logging Sucks。独立的 evlog CLI 可以帮助你探索日志，并通过静态检查发现缺失的日志记录模式。

哲学

传统日志记录已失效。你的日志分散在数十个文件中。每个请求生成超过 10 行日志。当出现问题时，你只能通过 grep 在噪音中寻找信号。

evlog 采用了不同的方法：

结构化日志

用类型化、结构化的事件替代 console.log，并通过 drain 管线流转。拥有与 pino 或 consola 相同的级别过滤、脱敏以及美化/JSON 输出。

广泛事件

在任意工作单元（请求、脚本或任务）中累积上下文，并一次性发出。两种模式可以共存，彼此都不是对方的升级版。

结构化错误

解释为什么发生以及如何修复的错误。

对开发者友好

开发阶段人类可读，生产环境为可解析的 JSON。

没有运行 HTTP 框架？请参阅用于脚本、工作器和 CLI 的独立 TypeScript，以及用于边缘运行时的 Cloudflare Workers。

为什么选择 evlog，而不是 pino、winston 或 consola

evlog 是一个功能完整的通用日志记录器，恰好也支持广泛事件。具体来说：

核心包没有运行时依赖。 从日志记录器开始，并根据需要添加集成。有关包体积和基准测试，请参阅性能。
在每种上下文中使用相同的 API：脚本、框架、边缘运行时、浏览器、库代码。没有 pino-http 与 pino 的拆分，也不需要为每种环境单独配置 consola 报告器。
内置 why / fix / link 的结构化错误：你的错误提示终于能告诉用户发生了什么以及该怎么做，你的值班人员也不必再逆向分析堆栈跟踪。
广泛事件是一条无需额外成本的升级路径：当你需要关联一次操作中的上下文时，同一个日志记录器会为你提供 log.set + log.emit，而不是事后再拼接日志行。

请查看完整的功能对比（对等矩阵、诚实的差距和迁移片段），与 pino、winston 和 consola 逐项比较。

选择三种日志记录方式之一

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: '卡被发卡行拒绝（余额不足）',
  fix: '尝试其他支付方式或联系你的银行',
  link: 'https://docs.example.com/payments/declined',
})

{
  "statusCode": 402,
  "message": "Payment failed",
  "data": {
    "why": "卡被发卡行拒绝（余额不足）",
    "fix": "尝试其他支付方式或联系你的银行",
    "link": "https://docs.example.com/payments/declined"
  }
}

为什么一个事件胜过十行日志

我们正在进入一个 AI 代理构建、调试和维护应用程序的时代。这些代理需要 结构化上下文 才能有效工作：

why：根本原因，让代理理解哪里出了问题
fix：可操作的解决方案，供代理建议或应用
link：复杂问题的文档

传统的 console.log 和通用的 throw new Error() 无法提供可操作的上下文。evlog 的结构化输出旨在供人类和 AI 解析并采取行动。

下一步

试用 evlog： 按照安装和快速开始进行操作。
决定它是否适合你的项目： 阅读选择 TypeScript 日志记录器，或者如果你要开发新应用，请阅读为什么从 evlog 开始。
探索相关概念： 日志记录概览将简单日志、广泛事件和结构化错误串联起来。

Edit this pageorReport an issue

为什么从 evlog 开始

添加结构化日志最省成本的时机是在第一次请求之前。在第 0 天选择 evlog，系统的其余部分都会继承它。