适配器

OTLP 适配器

通过 OpenTelemetry Protocol (OTLP) 向 Grafana、Datadog、Honeycomb 以及任何兼容的后端发送日志。支持 gRPC 和 HTTP 传输。

OTLP (OpenTelemetry Protocol) 适配器以标准的 OpenTelemetry 格式发送日志。这适用于任何兼容 OTLP 的后端，包括：

Grafana Cloud (Loki)
Datadog
Honeycomb
Jaeger
Splunk
New Relic
自建 OpenTelemetry Collector
HyperDX

提示

添加 OTLP 排水适配器以通过 OpenTelemetry Protocol 发送 evlog 广泛事件。

1. 确定我正在使用的框架并遵循其 evlog 集成模式
2. 如果尚未安装 evlog，请安装它
3. 从 'evlog/otlp' 导入 createOTLPDrain
4. 将 createOTLPDrain() 连接到我的框架的排水配置中
5. 设置 OTLP_ENDPOINT 环境变量（收集器 URL）
6. 可选设置 OTLP_HEADERS 用于身份验证
7. 通过触发请求进行测试，并检查您的 OTLP 后端（Grafana、Datadog、Honeycomb 等）

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

安装

OTLP 适配器与 evlog 一起打包提供：

src/index.ts

import { createOTLPDrain } from 'evlog/otlp'

快速开始

1. 设置您的 OTLP 端点

.env

OTLP_ENDPOINT=http://localhost:4318

2. 将排水连接到您的框架

// server/plugins/evlog-drain.ts
import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

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

import { createOTLPDrain } from 'evlog/otlp'

initLogger({ drain: createOTLPDrain() })

配置

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

传递给 createOTLPDrain() 的覆盖项
运行时配置 runtimeConfig.otlp（仅限 Nuxt/Nitro）
环境变量

环境变量

变量	Nuxt 别名	描述
`OTLP_ENDPOINT`	`NUXT_OTLP_ENDPOINT`	OTLP HTTP 端点（例如 `http://localhost:4318`）
`OTLP_SERVICE_NAME`	`NUXT_OTLP_SERVICE_NAME`	覆盖服务名称
`OTLP_HEADERS`	`NUXT_OTLP_HEADERS`	自定义 HTTP 标头（格式：`Key=Value,Key2=Value2`）
`OTLP_AUTH`	`NUXT_OTLP_AUTH`	`Authorization` 标头的快捷方式

标准 OpenTelemetry 变量也作为后备支持：

变量	描述
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP 端点
`OTEL_EXPORTER_OTLP_HEADERS`	OTEL 格式的标头
`OTEL_SERVICE_NAME`	服务名称

运行时配置（仅限 Nuxt）

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    otlp: {
      endpoint: '', // 通过 NUXT_OTLP_ENDPOINT 设置
    },
  },
})

覆盖选项

server/plugins/evlog-drain.ts

const drain = createOTLPDrain({
  endpoint: 'http://localhost:4318',
  serviceName: 'my-api',
  headers: {
    'Authorization': 'Bearer xxx',
  },
  resourceAttributes: {
    'deployment.environment': 'staging',
  },
})

完整配置参考

选项	类型	默认值	描述
`endpoint`	`string`	-	OTLP HTTP 端点（必需）
`serviceName`	`string`	来自事件	覆盖 `service.name` 资源属性
`headers`	`object`	-	用于身份验证的自定义 HTTP 标头
`resourceAttributes`	`object`	-	额外的 OTLP 资源属性
`timeout`	`number`	`5000`	请求超时（毫秒）

提供商特定设置

Grafana Cloud

转到您的 Grafana Cloud 门户
导航到 Connections > Collector > OpenTelemetry
复制您的 OTLP 端点并生成凭据

.env

OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic%20base64-encoded-credentials

Grafana 使用 URL 编码的标头。%20 是空格字符。适配器会自动解码此格式。

Datadog

.env

OTLP_ENDPOINT=https://http-intake.logs.datadoghq.com
OTLP_HEADERS=DD-API-KEY=your-api-key

本地 OpenTelemetry Collector

对于开发和测试，请运行本地收集器：

otel-collector.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [debug]

终端

docker run --rm -p 4318:4318 \
  -v $(pwd)/otel-collector.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest

.env

OTLP_ENDPOINT=http://localhost:4318

OTLP 日志格式

evlog 将广泛事件映射到 OTLP 日志格式：

evlog 字段	OTLP 字段
`level`	`severityNumber` / `severityText`
`timestamp`	`timeUnixNano`
`service`	资源属性 `service.name`
`environment`	资源属性 `deployment.environment`
`version`	资源属性 `service.version`
`region`	资源属性 `cloud.region`
`traceId`	`traceId`
`spanId`	`spanId`
所有其他字段	日志属性

严重性映射

evlog 级别	OTLP 严重性编号	OTLP 严重性文本
`debug`	5	DEBUG
`info`	9	INFO
`warn`	13	WARN
`error`	17	ERROR

故障排除

缺少端点错误

控制台

[evlog/otlp] 缺少端点。请设置 OTLP_ENDPOINT 或 OTEL_EXPORTER_OTLP_ENDPOINT

请确保设置了端点环境变量并且服务器已重新启动。

401 未授权

您的身份验证标头可能缺失或无效。请检查：

OTEL_EXPORTER_OTLP_HEADERS 格式是否正确
凭据是否有效且未过期
端点 URL 是否正确

404 未找到

适配器发送到 /v1/logs。请确保您的端点：

支持 OTLP HTTP（而非 gRPC）
是基础 URL，不包含 /v1/logs 后缀

日志未显示

检查服务器控制台是否有 [evlog/otlp] 错误消息
首先使用本地收集器测试以验证格式
检查后端的摄取延迟（某些后端有 1-2 分钟的延迟）

直接 API 用法

对于高级用例：

server/utils/otlp.ts

import { sendToOTLP, sendBatchToOTLP, toOTLPLogRecord } from 'evlog/otlp'

// 发送单个事件
await sendToOTLP(event, {
  endpoint: 'http://localhost:4318',
})

// 发送多个事件
await sendBatchToOTLP(events, {
  endpoint: 'http://localhost:4318',
})

// 将事件转换为 OTLP 格式（用于检查）
const otlpRecord = toOTLPLogRecord(event)

下一步

Axiom 适配器 - 将日志发送到 Axiom
PostHog 适配器 - 将日志发送到 PostHog
自定义适配器 - 构建您自己的适配器
最佳实践 - 安全性和生产提示

Edit this pageorReport an issue

Axiom

将广泛事件发送到 Axiom 以进行强大的查询、仪表板和告警。零配置设置，使用环境变量和自动批处理。

PostHog

通过 OTLP 将广泛事件发送到 PostHog Logs，用于结构化日志查询、调试和监控。