HyperDX 适配器

HyperDX 是一个开源可观测性平台。evlog HyperDX 适配器使用 OTLP over HTTP 将你的广泛事件发送到 HyperDX，默认设置与 HyperDX 的 OpenTelemetry 文档 一致。

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

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

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

安装

HyperDX 适配器随 evlog 一起捆绑提供：

import { createHyperDXDrain } from 'evlog/hyperdx'

快速开始

1. 获取你的摄取 API 密钥

1. 打开团队对应的 HyperDX 仪表板
2. 复制你的 摄取 API 密钥（HyperDX 在其 OpenTelemetry 示例中将其文档记录为 authorization 标头的值）

2. 设置环境变量

HYPERDX_API_KEY=<你的_HYPERDX_API_KEY_此处>

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

// server/plugins/evlog-drain.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

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

import { createHyperDXDrain } from 'evlog/hyperdx'

initLogger({ drain: createHyperDXDrain() })

就是这样！现在你的广泛事件将出现在 HyperDX 中。

配置

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

1. 传递给 createHyperDXDrain() 的覆盖选项
2. 运行时配置：runtimeConfig.evlog.hyperdx 或 runtimeConfig.hyperdx（仅限 Nuxt/Nitro）
3. 环境变量（HYPERDX_* 或 NUXT_HYPERDX_*）

环境变量

在解析 serviceName 时还会读取以下变量（与 OTLP 适配器相同）：

运行时配置（仅限 Nuxt）

可在 nuxt.config.ts 中进行类型安全的配置：

export default defineNuxtConfig({
  runtimeConfig: {
    hyperdx: {
      apiKey: '', // 通过 NUXT_HYPERDX_API_KEY 设置
      // endpoint: '', // 通过 NUXT_HYPERDX_OTLP_ENDPOINT 设置
    },
  },
})

你也可以将键嵌套在 runtimeConfig.evlog.hyperdx 下，两种方式都匹配适配器解析 Nuxt 运行时配置的方式。

覆盖选项

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

const drain = createHyperDXDrain({
  apiKey: process.env.HYPERDX_API_KEY!,
  endpoint: 'https://in-otel.hyperdx.io',
  timeout: 10000,
})

对于自托管 HyperDX，将 endpoint 设置为你的 OTLP HTTP 基础 URL（与 HyperDX 的 otlphttp 导出器示例中的 endpoint 作用相同）。

完整配置参考

工作原理

在内部，createHyperDXDrain() 将你的 HyperDX 设置映射到共享的 OTLP 适配器，并调用 sendBatchToOTLP()：

• 端点：OTLP HTTP 基础 URL，默认为 https://in-otel.hyperdx.io（evlog 发布到 {endpoint}/v1/logs）
• 认证：authorization 标头设置为你的 API 密钥（与 HyperDX 文档化的 otlphttp 导出器相同）
• 格式：标准的 OTLP JSON ExportLogsServiceRequest，包含严重级别、跟踪上下文（存在时）以及结构化属性

官方 HyperDX OpenTelemetry 参考

来自 HyperDX — OpenTelemetry：

我们的 OpenTelemetry HTTP 端点托管在 https://in-otel.hyperdx.io（gRPC 端口 4317），并且需要将 authorization 标头设置为你的 API 密钥。

HyperDX 文档化了此收集器配置（HTTP 和 gRPC 导出器）：

exporters:
  # HTTP 配置
  otlphttp/hdx:
    endpoint: 'https://in-otel.hyperdx.io'
    headers:
      authorization: <你的_HYPERDX_API_KEY_HERE>
    compression: gzip

  # gRPC 配置（备选）
  otlp/hdx:
    endpoint: 'in-otel.hyperdx.io:4317'
    headers:
      authorization: <你的_HYPERDX_API_KEY_HERE>
    compression: gzip

evlog 使用 HTTP 路径：以 Content-Type: application/json 将 JSON 发送到 {endpoint}/v1/logs，并附带上述 authorization 标头。收集器可能会启用 compression: gzip；evlog 会像典型的 OTLP HTTP 客户端一样发送未压缩的 JSON 正文。

在 HyperDX 中查询日志

使用 HyperDX UI 搜索和探索广泛事件：

• 搜索：根据你的广泛事件中的字段进行过滤（级别、服务、路径、自定义属性等）
• 实时追踪：流式传输传入的日志
• 仪表板：在结构化日志数据之上构建视图

故障排除

缺少 apiKey 错误

[evlog/hyperdx] 缺少 apiKey。请设置 HYPERDX_API_KEY 或 NUXT_HYPERDX_API_KEY，或通过 createHyperDXDrain() 传递

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

401 未授权或摄入被拒绝

你的 API 密钥可能无效或不允许摄取。请确认 HyperDX 中的密钥与他们的 OpenTelemetry 示例中使用的摄取密钥匹配（authorization: <你的_HYPERDX_API_KEY_HERE>）。

直接 API 使用

对于高级用例，你可以使用更低级的函数：

import { sendToHyperDX, sendBatchToHyperDX } from 'evlog/hyperdx'

// 发送单个事件
await sendToHyperDX(event, {
  apiKey: process.env.HYPERDX_API_KEY!,
})

// 批量发送多个事件
await sendBatchToHyperDX(events, {
  apiKey: process.env.HYPERDX_API_KEY!,
  endpoint: 'https://in-otel.hyperdx.io',
})

下一步

• OTLP 适配器 - 通过 OpenTelemetry 协议将日志发送到任何 OTLP 后端
• PostHog 适配器 - 通过 OTLP 将日志发送到 PostHog Logs
• 自定义适配器 - 构建你自己的适配器
• 最佳实践 - 安全性和生产环境提示