一套 OTel 埋点,同时接入 Datadog 和 Langfuse
自 2025 年 12 月 Datadog 采纳 OTel GenAI 约定,客户换工具不必再重写应用代码。
要点速览
- Datadog 现已原生支持 OTel GenAI 语义约定,覆盖 GenAI 约定 v1.37 及以后版本;Langfuse 也以符合同一套约定为目标。
- LLM 应用只需埋点一次,由 OTel Collector 把 trace 分发到多个后端。
- Langfuse 只接受基于 HTTP 的 OTLP,不支持 gRPC;与 Datadog 共用管道时,这是最容易犯的错。
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 按各厂商文档填写:
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 文件去解决。
这篇文章对你有帮助吗?
感谢你的反馈!
5 个信源
- Datadog Agent Observability natively supports OpenTelemetry GenAI Semantic Conventions · 2025-12-01
- OpenTelemetry Instrumentation
- OpenTelemetry (OTEL) for LLM Observability
- semantic-conventions/docs/gen-ai/gen-ai-spans.md at main · open-telemetry/semantic-conventions
- GitHub - open-telemetry/semantic-conventions-genai