# 一套 OTel 埋点，同时接入 Datadog 和 Langfuse

> 自 2025 年 12 月 Datadog 采纳 OTel GenAI 约定，客户换工具不必再重写应用代码。

原文: https://fdetimes.net/zh/tools/opentelemetry-llm-traces-datadog-langfuse/

2025 年 12 月，Datadog 宣布其 LLM/Agent Observability 产品原生支持 OpenTelemetry GenAI 语义约定，覆盖 1.37 及以后版本。

这看起来只是一条更新日志，却解开了企业 LLM 项目里几乎每个前线部署工程师（FDE）都会遇到的一个结：客户的运维团队已经在用 Datadog，数据团队却想把 trace 留在自托管的 Langfuse 里。

如果每个后端都要求接入自己的 SDK，应用代码就会和厂商焊死。有了共同标准，问题就变了。Langfuse 同样表示以符合 OpenTelemetry GenAI 约定为目标，因此一次埋点就能同时服务两边。

这正是 FDE 在客户现场要做的事：设计好数据管道，让客户的工具选择不会逼着团队重写应用代码。

## OTel GenAI 到底标准化了什么？

OpenTelemetry 是一套面向 trace、指标和日志的开放标准。GenAI 部分为模型调用补充了一组统一的属性名，任何收到 trace 的后端都能分辨哪个 span 是 LLM 调用、哪个属性存的是什么。

权威来源已经换了地方。GenAI 约定已从通用的 semantic-conventions 仓库拆出，独立成 semantic-conventions-genai 仓库，涵盖 GenAI 客户端的 span、指标和事件。和客户讨论某个属性名时，请引用新仓库，而不是旧页面。

Datadog 对这种做法的描述很简洁：用 OTel 给 LLM 应用埋点一次，再通过现有的 OTel Collector 管道导出 GenAI span。其文档还说明，OTel trace 可以直接发送，无需 Agent Observability SDK，也无需 Datadog Agent。

## FDE 什么时候该在客户现场用它？

设想一家银行客户。SRE 团队希望在 Datadog 里把 Agent 延迟和基础设施看板放在一起；AI 团队希望在内部部署的 Langfuse 里查看每一条 prompt 和响应。如果装两套 SDK，每次改框架都得改两遍，两个团队看到的画面还会越来越不一致。

更干净的做法是：按 OTel GenAI 埋点，全部发到同一个 OTel Collector，再由 Collector 把同一条 trace 拆成两条并行分支。如果客户还没选定厂商，这种做法更合适，因为以后换后端只需改 exporter 配置。

**要点:** 按开放标准埋点，让厂商选择留在配置文件里，而不是写进代码。

## 一份最小化的 Collector 配置

这份配置的关键在两个细节。Datadog 通过 header `dd-otlp-source=llmobs` 把 OTLP span 路由到 Agent Observability。Langfuse（包括自托管部署）在 `/api/public/otel` 端点接收 OTLP trace。大致写法如下，端点和认证 header 按各厂商文档填写：

```yaml
receivers:
  otlp:
    protocols:
      http:
      grpc:

exporters:
  otlphttp/datadog:
    endpoint: <DATADOG_OTLP_ENDPOINT>
    headers:
      dd-otlp-source: llmobs
      # 按 Datadog 文档添加 API key header
  otlphttp/langfuse:
    endpoint: <LANGFUSE_HOST>/api/public/otel
    headers:
      # 按 Langfuse 文档添加认证 header

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/datadog, otlphttp/langfuse]
```

（配置中的注释意为：按 Datadog 文档添加 API key header；按 Langfuse 文档添加认证 header。）

对 Langfuse 来说，`otlphttp` 是必需的。Langfuse 支持基于 HTTP 的 OTLP，HTTP/JSON 和 HTTP/protobuf 都可以，但暂不支持 gRPC。

Datadog 则不同。这份示例给它也用 `otlphttp`，是为了让两条分支使用同一种 exporter，配置更易读、更好排查；这并不是 Langfuse 带来的限制。如果客户现有管道已经用别的 exporter 把 trace 发到 Datadog 且运行正常，就别动那条分支，只为 Langfuse 单独加一个 HTTP exporter。

改动之前，先查 Datadog 文档，确认客户的端点接受哪些协议。

## 收工前先验证

Collector 启动不报错还不算完。从应用发出恰好一次测试 LLM 调用，然后打开两个后端查找这条 trace：Datadog 看 LLM/Agent Observability 视图，Langfuse 看项目的 trace 列表。

如果 trace 只在一边出现，问题范围就已经缩小了。Langfuse 里没有：复查 HTTP 协议、`/api/public/otel` 路径和正在运行的版本。Datadog 的 LLM 视图里没有：复查 `dd-otlp-source` header 和框架输出的约定版本。

## 演示前的三个陷阱

第一个陷阱是 gRPC，前文已经讲过。第二个是版本：Langfuse 建议自托管用户在 OTel 端点遇到 4xx 错误时升级到最新版本，其文档写明本地部署需要 v3.22.0 或更高版本。在怀疑 Collector 配置之前，先问客户跑的是哪个 Langfuse 版本。

第三个陷阱在框架里。很多库早于 1.37 版约定。Datadog 文档要求设置环境变量 `OTEL_SEMCONV_STABILITY_OPT_IN`，让它们输出兼容 1.37+ 的 trace。如果 Datadog 收到了 span，LLM 视图里却看不到，先查这一项。

还值得知道的是，Datadog 不只接受 OTel GenAI，也接受遵循 OpenInference 约定的 trace。客户已经用 OpenInference 埋过点时，这一点很有用；但不要据此认定 Langfuse 会以完全相同的方式解读它们。两者确定共有的基础是 OTel GenAI。

## 先学什么

先学 OTel Collector，而不是看板。弄懂 receiver、exporter 和 pipeline，就足以在一个下午搭出上面的配置。然后阅读 semantic-conventions-genai 仓库的 spans 部分，再与你所用框架实际输出的 trace 对照。

看 FDE 岗位描述时，留意“observability”“OpenTelemetry”“LLM tracing”这类字眼。简历上写一句“基于 OTel GenAI 搭建 LLM tracing 管道，并行导出到 Datadog 和自托管 Langfuse”，比罗列一串工具名更有说服力。

如果客户还在比较可观测性工具，不必等他们拍板。一条符合标准的 OTel 管道让你今天就能开始收集 trace，那场争论留给一个 YAML 文件去解决。

**本周动手试试:**

- 部署一个较新的自托管 Langfuse，把 Collector 的 otlphttp exporter 指向 /api/public/otel，再从一个小型 LLM 应用发送一条测试 trace。
- 打开 OpenTelemetry 的 semantic-conventions-genai 仓库，阅读 spans 部分，列出你当前框架实际输出的 gen_ai 属性。
- 在简历上加一行，描述一条与厂商无关的 LLM tracing 管道：用 OTel 埋点，经 Collector 分发，至少接入两个后端。

## 信源

- [Datadog Agent Observability natively supports OpenTelemetry GenAI Semantic Conventions](https://www.datadoghq.com/blog/llm-otel-semantic-convention/)

- [OpenTelemetry Instrumentation](https://docs.datadoghq.com/llm_observability/instrument/otel_instrumentation/)

- [OpenTelemetry (OTEL) for LLM Observability](https://langfuse.com/integrations/native/opentelemetry)

- [semantic-conventions/docs/gen-ai/gen-ai-spans.md at main · open-telemetry/semantic-conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md)

- [GitHub - open-telemetry/semantic-conventions-genai](https://github.com/open-telemetry/semantic-conventions-genai)
