---
title: "HyperDX 适配器"
description: "通过 OTLP/HTTP，使用其文档中说明的端点和授权标头，将广泛事件发送到 HyperDX。通过环境变量进行配置。"
canonical_url: "https://evlog.zhcndoc.com/integrate/adapters/hybrid/hyperdx"
---
# HyperDX 适配器

> 通过 OTLP/HTTP，使用其文档中说明的端点和授权标头，将广泛事件发送到 HyperDX。通过环境变量进行配置。

[HyperDX](https://hyperdx.io) 是一个开源可观测性平台。evlog HyperDX 适配器使用 **OTLP over HTTP** 将你的广泛事件发送到 HyperDX，默认设置与 [HyperDX 的 OpenTelemetry 文档](https://hyperdx.io/docs/install/opentelemetry) 一致。

<prompt :actions="["copy","cursor","claude"]" description="添加 HyperDX 排水适配器" icon="i-custom-hyperdx">

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

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

适配器文档：[https://www.evlog.dev/integrate/adapters/hybrid/hyperdx](https://www.evlog.dev/integrate/adapters/hybrid/hyperdx)
框架设置：[https://www.evlog.dev/integrate/frameworks/overview](https://www.evlog.dev/integrate/frameworks/overview)

</prompt>

## 安装

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

```typescript [src/index.ts]
import { createHyperDXDrain } from 'evlog/hyperdx'
```

## 快速开始

### 1. 获取你的摄取 API 密钥

1. 打开团队对应的 [HyperDX](https://hyperdx.io) 仪表板
2. 复制你的 **摄取 API 密钥**（HyperDX 在其 OpenTelemetry 示例中将其文档记录为 `authorization` 标头的值）

### 2. 设置环境变量

```bash [.env]
HYPERDX_API_KEY=<你的_HYPERDX_API_KEY_此处>
```

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

<framework-tabs>

```typescript [Nuxt]server/plugins/evlog-drain.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Nitro]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Next.js]lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createHyperDXDrain(),
})
```

```typescript [SvelteKit]src/hooks.server.ts
import { createEvlogHooks } from 'evlog/sveltekit'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { handle, handleError } = createEvlogHooks({ drain: createHyperDXDrain() })
```

```typescript [TanStack Start]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [React Router]app/root.tsx
import { evlog } from 'evlog/react-router'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const middleware: Route.MiddlewareFunction[] = [
  evlog({ drain: createHyperDXDrain() }),
]
```

```typescript [Hono]src/index.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Express]src/index.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Fastify]src/index.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Elysia]src/index.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [NestJS]src/app.module.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [oRPC]server/orpc.ts
import { withEvlog } from 'evlog/orpc'
import { createHyperDXDrain } from 'evlog/hyperdx'

const handler = withEvlog(new RPCHandler(router), { drain: createHyperDXDrain() })
```

```typescript [Cloudflare Workers]src/worker.ts
import { withEvlog } from 'evlog/workers'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default withEvlog(handler, { drain: createHyperDXDrain() })
```

```typescript [Standalone]
import { createHyperDXDrain } from 'evlog/hyperdx'

initLogger({ drain: createHyperDXDrain() })
```

</framework-tabs>

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

## 配置

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

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

### 环境变量

<table>
<thead>
  <tr>
    <th>
      变量
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        HYPERDX_API_KEY
      </code>
    </td>
    
    <td>
      接收摄取 API 密钥（作为 <code>
        authorization
      </code>
      
       请求头发送）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        HYPERDX_OTLP_ENDPOINT
      </code>
    </td>
    
    <td>
      OTLP HTTP 基础 URL（默认值：<code>
        https://in-otel.hyperdx.io
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        HYPERDX_SERVICE_NAME
      </code>
    </td>
    
    <td>
      覆盖 <code>
        service.name
      </code>
    </td>
  </tr>
</tbody>
</table>

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

<table>
<thead>
  <tr>
    <th>
      变量
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        OTEL_SERVICE_NAME
      </code>
    </td>
    
    <td>
      服务名的备选值（HyperDX SDK 示例中使用此值）
    </td>
  </tr>
</tbody>
</table>

### 运行时配置（仅限 Nuxt）

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

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    hyperdx: {
      apiKey: '', // 通过 HYPERDX_API_KEY 设置
      // endpoint: '', // 通过 HYPERDX_OTLP_ENDPOINT 设置
    },
  },
})
```

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

### 覆盖选项

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

<framework-tabs>

```typescript [Nuxt]server/plugins/evlog-drain.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }))
})
```

```typescript [Nitro]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }))
})
```

```typescript [Next.js]lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }),
})
```

```typescript [SvelteKit]src/hooks.server.ts
import { createEvlogHooks } from 'evlog/sveltekit'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [TanStack Start]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }))
})
```

```typescript [React Router]app/root.tsx
import { evlog } from 'evlog/react-router'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const middleware: Route.MiddlewareFunction[] = [
  evlog({
      drain: createHyperDXDrain({
        apiKey: process.env.HYPERDX_API_KEY!,
        endpoint: 'https://in-otel.hyperdx.io',
        timeout: 10000,
      }),
    }),
]
```

```typescript [Hono]src/index.ts
import { evlog } from 'evlog/hono'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Express]src/index.ts
import { evlog } from 'evlog/express'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Fastify]src/index.ts
import { evlog } from 'evlog/fastify'
import { createHyperDXDrain } from 'evlog/hyperdx'

await app.register(evlog, {
  drain: createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }),
})
```

```typescript [Elysia]src/index.ts
import { evlog } from 'evlog/elysia'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [NestJS]src/app.module.ts
import { EvlogModule } from 'evlog/nestjs'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [oRPC]server/orpc.ts
import { withEvlog } from 'evlog/orpc'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Cloudflare Workers]src/worker.ts
import { withEvlog } from 'evlog/workers'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default withEvlog(handler, {
  drain: createHyperDXDrain({
    apiKey: process.env.HYPERDX_API_KEY!,
    endpoint: 'https://in-otel.hyperdx.io',
    timeout: 10000,
  }),
})
```

```typescript [Standalone]src/index.ts
import { initLogger } from 'evlog'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

</framework-tabs>

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

### 完整配置参考

<table>
<thead>
  <tr>
    <th>
      选项
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        apiKey
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      摄取 API 密钥（必需）。作为 <code>
        authorization
      </code>
      
       标头的值发送
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endpoint
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://in-otel.hyperdx.io
      </code>
    </td>
    
    <td>
      OTLP HTTP 基础 URL（evlog 在其后追加 <code>
        /v1/logs
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        serviceName
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      覆盖 <code>
        service.name
      </code>
      
       资源属性
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resourceAttributes
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      额外的 OTLP 资源属性
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        5000
      </code>
    </td>
    
    <td>
      请求超时时间（毫秒）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        retries
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        2
      </code>
    </td>
    
    <td>
      瞬态错误重试次数
    </td>
  </tr>
</tbody>
</table>

## 部署

HyperDX 是开源的，因此适配器使用相同的代码，同时支持托管账户和你自行运行的集群。只有 `endpoint` 会发生变化。

### HyperDX 云端

默认配置。设置 API 密钥即可：

<framework-tabs>

```typescript [Nuxt]server/plugins/evlog-drain.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Nitro]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Next.js]lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createHyperDXDrain(),
})
```

```typescript [SvelteKit]src/hooks.server.ts
import { createEvlogHooks } from 'evlog/sveltekit'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { handle, handleError } = createEvlogHooks({ drain: createHyperDXDrain() })
```

```typescript [TanStack Start]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [React Router]app/root.tsx
import { evlog } from 'evlog/react-router'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const middleware: Route.MiddlewareFunction[] = [
  evlog({ drain: createHyperDXDrain() }),
]
```

```typescript [Hono]src/index.ts
import { evlog } from 'evlog/hono'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Express]src/index.ts
import { evlog } from 'evlog/express'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Fastify]src/index.ts
import { evlog } from 'evlog/fastify'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [Elysia]src/index.ts
import { evlog } from 'evlog/elysia'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [NestJS]src/app.module.ts
import { EvlogModule } from 'evlog/nestjs'
import { createHyperDXDrain } from 'evlog/hyperdx'

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

```typescript [oRPC]server/orpc.ts
import { withEvlog } from 'evlog/orpc'
import { createHyperDXDrain } from 'evlog/hyperdx'

const handler = withEvlog(new RPCHandler(router), { drain: createHyperDXDrain() })
```

```typescript [Cloudflare Workers]src/worker.ts
import { withEvlog } from 'evlog/workers'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default withEvlog(handler, { drain: createHyperDXDrain() })
```

```typescript [Standalone]src/index.ts
import { initLogger } from 'evlog'
import { createHyperDXDrain } from 'evlog/hyperdx'

initLogger({ drain: createHyperDXDrain() })
```

</framework-tabs>

```bash [.env]
HYPERDX_API_KEY=your-ingestion-key
```

端点默认为 `https://in-otel.hyperdx.io`。

### 自托管

将 `endpoint` 指向你自己的 OTLP HTTP 收集器，与在 `otlphttp` 导出器的 `endpoint` 中填写的值相同：

<framework-tabs>

```typescript [Nuxt]server/plugins/evlog-drain.ts
import { createHyperDXDrain } from 'evlog/hyperdx'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }))
})
```

```typescript [Nitro]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }))
})
```

```typescript [Next.js]lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }),
})
```

```typescript [SvelteKit]src/hooks.server.ts
import { createEvlogHooks } from 'evlog/sveltekit'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const { handle, handleError } = createEvlogHooks({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

```typescript [TanStack Start]server/plugins/evlog-drain.ts
import { definePlugin } from 'nitro'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }))
})
```

```typescript [React Router]app/root.tsx
import { evlog } from 'evlog/react-router'
import { createHyperDXDrain } from 'evlog/hyperdx'

export const middleware: Route.MiddlewareFunction[] = [
  evlog({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) }),
]
```

```typescript [Hono]src/index.ts
import { evlog } from 'evlog/hono'
import { createHyperDXDrain } from 'evlog/hyperdx'

app.use(evlog({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) }))
```

```typescript [Express]src/index.ts
import { evlog } from 'evlog/express'
import { createHyperDXDrain } from 'evlog/hyperdx'

app.use(evlog({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) }))
```

```typescript [Fastify]src/index.ts
import { evlog } from 'evlog/fastify'
import { createHyperDXDrain } from 'evlog/hyperdx'

await app.register(evlog, { drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

```typescript [Elysia]src/index.ts
import { evlog } from 'evlog/elysia'
import { createHyperDXDrain } from 'evlog/hyperdx'

app.use(evlog({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) }))
```

```typescript [NestJS]src/app.module.ts
import { EvlogModule } from 'evlog/nestjs'
import { createHyperDXDrain } from 'evlog/hyperdx'

EvlogModule.forRoot({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

```typescript [oRPC]server/orpc.ts
import { withEvlog } from 'evlog/orpc'
import { createHyperDXDrain } from 'evlog/hyperdx'

const handler = withEvlog(new RPCHandler(router), { drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

```typescript [Cloudflare Workers]src/worker.ts
import { withEvlog } from 'evlog/workers'
import { createHyperDXDrain } from 'evlog/hyperdx'

export default withEvlog(handler, { drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

```typescript [Standalone]src/index.ts
import { initLogger } from 'evlog'
import { createHyperDXDrain } from 'evlog/hyperdx'

initLogger({ drain: createHyperDXDrain({ endpoint: 'http://hyperdx.internal:4318' }) })
```

</framework-tabs>

```bash [.env]
HYPERDX_OTLP_ENDPOINT=http://hyperdx.internal:4318
# 仅当你的部署强制要求身份验证时：
HYPERDX_API_KEY=your-key
```

<callout color="info" icon="i-lucide-info">

填写**基础** URL，而不是信号路径。evlog 会自行追加 `/v1/logs`。默认 OTLP HTTP 端口上的自托管收集器地址为 `http://host:4318`。

</callout>

## 工作原理

在底层，`createHyperDXDrain()` 会将你的 HyperDX 设置映射到共享的 [OTLP 适配器](https://evlog.zhcndoc.com/integrate/adapters/hybrid/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 设置](https://hyperdx.io/docs/install/opentelemetry)：

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

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

```yaml [OpenTelemetry HyperDX 导出器]
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 用户界面搜索和探索广泛事件：

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

## 故障排除

### 缺少 apiKey 错误

```text [Console]
[evlog/hyperdx] Missing apiKey. Set HYPERDX_API_KEY, or pass to createHyperDXDrain()
```

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

### 401 未授权或摄取被拒绝

你的 API 密钥可能无效或不允许摄取。请确认 HyperDX 中的密钥与他们的 [OpenTelemetry](https://hyperdx.io/docs/install/opentelemetry) 示例中使用的摄取密钥匹配（`authorization: <你的_HYPERDX_API_KEY_HERE>`）。

## 直接 API 使用

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

```typescript [server/utils/hyperdx.ts]
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 适配器](https://evlog.zhcndoc.com/integrate/adapters/hybrid/otlp) - 通过 OpenTelemetry 协议将日志发送到任意 OTLP 后端
- [PostHog 适配器](https://evlog.zhcndoc.com/integrate/adapters/cloud/posthog) - 通过 OTLP 将日志发送到 PostHog Logs
- [自定义适配器](https://evlog.zhcndoc.com/extend/custom-drains) - 构建你自己的适配器
- [最佳实践](https://evlog.zhcndoc.com/reference/best-practices) - 安全性与生产环境提示。

---

- [HyperDX](https://hyperdx.io)
- [OTLP 适配器](https://evlog.zhcndoc.com/integrate/adapters/hybrid/otlp)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.