Sentry 适配器

Sentry 是一个错误追踪与性能监控平台。evlog Sentry 适配器会将你的宽事件以 Sentry 结构化日志 的形式发送，在 Sentry 控制台的 Explore > Logs 中可见，并支持高基数可搜索属性。

添加 Sentry 排水适配器以将 evlog 宽事件发送到 Sentry 日志。

1. 确定我正在使用的框架并遵循其 evlog 集成模式
2. 如果尚未安装 evlog，请安装它
3. 从 'evlog/sentry' 导入 createSentryDrain
4. 将 createSentryDrain() 连接到我的框架的排水配置
5. 设置 SENTRY_DSN 环境变量
6. 通过触发请求进行测试，并在 Sentry > Explore > Logs 中检查

适配器文档: https://www.evlog.dev/adapters/sentry
框架设置: https://www.evlog.dev/frameworks

安装

Sentry 适配器已与 evlog 捆绑提供：

import { createSentryDrain } from 'evlog/sentry'

快速开始

1. 获取你的 Sentry DSN

1. 创建一个 Sentry 账户
2. 创建一个新的项目（Node.js 或 JavaScript）
3. 在 Settings > Projects > 你的项目 > Client Keys (DSN) 中找到你的 DSN

2. 设置环境变量

SENTRY_DSN=https://your-public-key@o0.ingest.sentry.io/your-project-id

3. 将排水器连接到你的框架

// server/plugins/evlog-drain.ts
import { createSentryDrain } from 'evlog/sentry'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createSentryDrain())
})

import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))

import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))

import { createSentryDrain } from 'evlog/sentry'

await app.register(evlog, { drain: createSentryDrain() })

import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))

import { createSentryDrain } from 'evlog/sentry'

EvlogModule.forRoot({ drain: createSentryDrain() })

import { createSentryDrain } from 'evlog/sentry'

initLogger({ drain: createSentryDrain() })

就这样！你的日志现在会出现在 Sentry 的 Explore > Logs 中。

配置

适配器按照优先级顺序从多个来源读取配置（优先级从高到低）：

1. 传递给 createSentryDrain() 的覆盖项
2. 运行时配置 runtimeConfig.sentry（仅限 Nuxt/Nitro）
3. 环境变量（SENTRY_* 或 NUXT_SENTRY_*）

环境变量

运行时配置（仅限 Nuxt）

通过在 nuxt.config.ts 中配置，实现类型安全的配置：

export default defineNuxtConfig({
  modules: ['evlog/nuxt'],
  evlog: {
    sentry: {
      dsn: '', // 通过 NUXT_SENTRY_DSN 设置
      environment: 'production',
      release: '1.0.0',
    },
  },
})

覆盖选项

直接传递选项以覆盖任何配置：

const drain = createSentryDrain({
  dsn: 'https://key@o0.ingest.sentry.io/123',
  tags: { team: 'backend' },
  timeout: 10000,
})

完整配置参考

日志转换

evlog 宽事件通过 toSentryLog() 转换为 Sentry 日志：

• 等级映射：evlog 等级直接映射（debug、info、warn、error）
• 严重性数字：遵循 OpenTelemetry 规范（debug=5、info=9、warn=13、error=17）
• 正文：来自事件的 message、action 或 path 字段（按可用性优先）
• 属性：所有宽事件字段作为类型化属性发送（字符串、整数、浮点数、布尔值）。复杂对象会被序列化为 JSON 字符串。
• Sentry 属性：自动设置 sentry.environment 和 sentry.release
• 跟踪 ID：如果存在 event.traceId 则使用，否则生成随机值

在 Sentry 中查询日志

evlog 以结构化日志形式发送宽事件。在 Sentry 控制台中：

• Explore > Logs：查看所有 evlog 宽事件，并支持完整属性搜索
• 按属性过滤：如 service:my-app、level:error 或任意宽事件字段
• 跟踪关联：日志通过 trace_id 与跟踪关联，便于交叉引用

故障排除

缺少 DSN 错误

[evlog/sentry] 缺少 DSN。请设置 SENTRY_DSN 环境变量或在 createSentryDrain() 中传递

请确保已设置环境变量并在添加后重启服务器。

无效的 DSN

如果 DSN 格式错误（缺少公钥或项目 ID），适配器会抛出错误。请验证 DSN 格式：

https://<公钥>@<主机>/<项目ID>

401 未授权

你的 DSN 可能被吊销或无效。请在 Settings > Projects > Client Keys (DSN) 中生成新的 DSN。

直接 API 用法

对于高级用例，你可以使用底层函数：

import { sendToSentry, sendBatchToSentry } from 'evlog/sentry'

// 发送单个事件作为 Sentry 日志
await sendToSentry(event, {
  dsn: process.env.SENTRY_DSN!,
})

// 批量发送多个事件
await sendBatchToSentry(events, {
  dsn: process.env.SENTRY_DSN!,
})

下一步

• Axiom 适配器 - 将日志发送到 Axiom 以进行查询和仪表板展示
• OTLP 适配器 - 通过 OpenTelemetry 协议发送日志
• PostHog 适配器 - 将日志发送到 PostHog
• 自定义适配器 - 构建你自己的适配器