Datadog 适配器

Datadog 是一个监控和安全平台。evlog Datadog 适配器使用 HTTP 日志摄入 API (v2) 和 DD-API-KEY 标头，将你的广泛事件发送到 Datadog 日志。

对于基于 OpenTelemetry 的摄取，请参见 OTLP 适配器。

添加 Datadog 排水适配器以将 evlog 广泛事件发送到 Datadog 日志。

1. 确认我使用的框架并遵循其 evlog 集成模式
2. 如果尚未安装 evlog，请安装它
3. 从 'evlog/datadog' 导入 createDatadogDrain
4. 将 createDatadogDrain() 集成到框架的排水配置中
5. 在 .env 中设置 DD_API_KEY（或 DATADOG_API_KEY），并可选设置 DD_SITE
6. 通过触发请求进行测试，并在 Datadog 的日志资源管理器中查看结果

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

安装

Datadog 适配器与 evlog 捆绑提供：

import { createDatadogDrain } from 'evlog/datadog'

快速开始

1. 获取 API 密钥

1. 打开 Datadog 组织设置 → API 密钥
2. 创建或复制一个具有提交日志权限的 API 密钥

2. 设置环境变量

DD_API_KEY=your-api-key
# 可选 — 默认为 datadoghq.com (US1)
DD_SITE=datadoghq.eu

3. 将排水集成到框架中

// server/plugins/evlog-drain.ts
import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

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

import { createDatadogDrain } from 'evlog/datadog'

initLogger({ drain: createDatadogDrain() })

广泛事件将显示在 日志 → 资源管理器 中。适配器将 ddsource 设置为 evlog，并将 message 设置为完整广泛事件的 JSON 字符串，以便在管道中轻松解析 JSON。

配置

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

1. 传递给 createDatadogDrain() 的覆盖项
2. 运行时配置 — runtimeConfig.datadog 或 runtimeConfig.evlog.datadog（Nuxt/Nitro）
3. 环境变量 — 参见下表

环境变量

运行时配置（仅限 Nuxt）

export default defineNuxtConfig({
  runtimeConfig: {
    datadog: {
      apiKey: '', // 通过 NUXT_DATADOG_API_KEY 或 DD_API_KEY 设置
      site: 'datadoghq.eu',
    },
  },
})

覆盖选项

const drain = createDatadogDrain({
  apiKey: '***',
  site: 'us5.datadoghq.com',
  timeout: 10000,
})

完整配置参考

日志结构

每个广泛事件都会转换为一条 Datadog 日志，包含以下字段：

• message — 用于列表视图的单行摘要（例如 ERROR GET /api/checkout (400)），通过 formatDatadogMessageLine 构建。相比完整 JSON 字符串，在实时追踪中更易浏览。
• evlog — 完整的广泛事件作为 JSON 对象（而非字符串）。树中任何位置的数字 HTTP status 字段都会被重命名为 httpStatusCode，以避免与 Datadog 保留的严重级别 status 冲突。
• service、status（Datadog 严重级别 — 决定实时追踪颜色）、ddsource: evlog、ddtags: env:… 和可选的 version:…
• timestamp: 来自 WideEvent.timestamp 的 Unix 毫秒时间戳

摄入根级别的严重性（status） 由适配器根据广泛事件的 level 和 HTTP status 计算得出（参见 evlog/datadog 中的 resolveDatadogLogStatus）。HTTP 200 对应的业务字段仍为 info，除非显式调用 log.error()。

如需高级用法，sanitizeWideEventForDatadog(event) 返回的即为要存储在 evlog 下的清洗后对象。

在 Datadog 中查询

• 日志资源管理器: source:evlog, service:your-app, status:error
• 字段分面: 推荐使用 @evlog.path、@evlog.requestId、@evlog.level 等 — 核心字段位于 evlog 下，而不是 message 中的 JSON 字符串
• 指标: 基于 @evlog.* 属性创建基于日志的指标
• 管道: 如果你之前将完整 JSON 字符串解析到了 message，请将这些字段迁移到 @evlog.*。message 现在仅作为简短摘要行使用。

简单日志与广泛事件

实时追踪中的纯文本行（例如 “Form field is empty”）通常来自 log.info('tag', 'msg')，而非通过 emit() 发送的广泛事件。这些行输出到控制台（以及任何基于 Agent 的日志流），而 Datadog 排水器会为每个广泛事件发送一条结构化日志，来源为 source:evlog。

故障排除

缺少 API 密钥

[evlog/datadog] 缺少 API 密钥。请设置 NUXT_DATADOG_API_KEY、DATADOG_API_KEY 或 DD_API_KEY...

设置 DD_API_KEY（或无前缀的 DATADOG_API_KEY）并重启进程。

403 禁止访问

API 密钥可能缺少日志写入权限或属于错误的组织。请在 Datadog 中验证密钥并尝试使用新密钥。

区域/站点错误

如果日志未出现，请确认 DD_SITE 与你的 Datadog 账户匹配（例如欧盟：datadoghq.eu）。若使用自定义摄入 URL，请设置 DATADOG_LOGS_URL / NUXT_DATADOG_LOGS_URL。

直接 API 使用

import { sendToDatadog, sendBatchToDatadog } from 'evlog/datadog'

await sendToDatadog(event, {
  apiKey: process.env.DD_API_KEY!,
  site: process.env.DD_SITE,
})

await sendBatchToDatadog(events, {
  apiKey: process.env.DD_API_KEY!,
})

下一步

• OTLP 适配器 — 通过 OpenTelemetry 发送日志（适用于 Datadog Agent / OTLP 端点）
• 自定义适配器 — 构建你自己的目标