traceloop/openllmetry · 上手攻略

  • 仓库：traceloop/openllmetry
  • 链接：https://github.com/traceloop/openllmetry
  • 分类：ai
  • 作者：Tom
  • 更新：2026-07-14

这是什么

OpenLLMetry（发音「open-LL-metry」）是基于 OpenTelemetry 的开源 LLM 应用可观测性工具，由 Y Combinator 支持的 Traceloop 公司开发和维护（Apache 2.0 许可）。

它的核心思路：用 OpenTelemetry 标准采集 LLM 应用的全链路追踪数据，无需更换你现有的可观测性基础设施（Datadog、Grafana、New Relic、Sentry……），直接通过 OpenTelemetry 协议输出，插到哪里都行。

通俗来说：它在不改变你代码结构的前提下，给 LangChain/LlamaIndex/OpenAI 调用"安装行车记录仪"，让你清楚看到每一次 LLM 调用花了多久、Token 消耗多少、检索到了什么上下文、哪一步慢了。

解决什么问题

  • LLM 调用黑盒：开发者只知道发了什么 prompt、收到什么回复，中间的向量检索、工具调用、Token 消耗、延迟分布完全不透明。
  • 调试成本高：生产环境 LLM 输出不符合预期时，缺乏 trace 数据只能靠日志盲猜。
  • 多框架并存：一个项目可能同时用 LangChain + LlamaIndex + OpenAI Agents，每个框架的调试方式都不一样。
  • 换平台代价大：换可观测性供应商（如从 Datadog 迁到 Grafana）意味着重写接入代码，OpenLLMetry 用标准 OTLP 协议规避了这一点。
  • LLM Provider API 变更无感知：OpenTelemetry 语义约定（Semantic Conventions）现已引入 LLM 领域标准化，OpenLLMetry 跟进了这一进展。

快速安装

环境要求：Python 3.10+（LLM 应用开发主流环境）

方式一：Traceloop SDK（最简，两行代码接入）

pip install traceloop-sdk

from traceloop.sdk import Traceloop

# 一行启动全链路追踪
Traceloop.init()

# 本地开发时可禁用批处理，trace 立即可见
# Traceloop.init(disable_batch=True)

That's it。上述代码运行后，所有 LangChain、LlamaIndex、OpenAI、Anthropic 等支持的调用都会自动生成 trace，发送到配置的 OTLP 端点。

方式二：直接用 OpenTelemetry Instrumentations（如果你已有 OTEL 环境）

# OpenAI 调用追踪
pip install opentelemetry-instrumentation-openai

# Anthropic 调用追踪
pip install opentelemetry-instrumentation-anthropic

# Chroma 向量数据库追踪
pip install opentelemetry-instrumentation-chroma

# 注入所有已安装的 instrumentations
opentelemetry-instrumentation-agent

核心用法

1. 对接可观测性平台

OpenLLMetry 支持 20+ 主流后端，以 Datadog 和 Grafana 为例：

Datadog

import os
os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://api.datadoghq.com"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "dd-api-key=<YOUR_API_KEY>"

from traceloop.sdk import Traceloop
Traceloop.init()

Grafana Tempo / OTel Collector

import os
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://<your-collector>:4317"

from traceloop.sdk import Traceloop
Traceloop.init()

完整列表参见 Integrations 文档。

2. 追踪 LLM 调用

OpenLLMetry 自动在 trace 中记录：

Span 属性 内容
llm.model 模型名称（如 gpt-4o）
llm.token_count.prompt 输入 Token 数
llm.token_count.completion 输出 Token 数
llm.token_count.total 总 Token 数
llm.invocation_parameters temperature、max_tokens 等参数
llm.responses 完整回复内容
llm.wik_retrieval 检索到的上下文块（如用了 RAG）

注：生产环境建议对敏感 prompt/response 设置采样率，而非全量记录。

3. 追踪向量数据库

# Chroma 为例（pip install opentelemetry-instrumentation-chroma）
from opentelemetry.instrumentation.chroma import ChromaInstrumentor
ChromaInstrumentor().instrument()

支持的 Vector DB：Chroma、Milvus、Pinecone、Qdrant、Weaviate、LanceDB、Marqo。

4. 追踪 LangChain / LlamaIndex 应用

# LangChain
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
# Traceloop.init() 后所有调用自动追踪

# LlamaIndex
from llama_index.core import Settings
# 同样，初始化后自动工作

支持的框架：LangChain、LangGraph、LangFlow、LlamaIndex、LiteLLM、CrewAI、Haystack、OpenAI Agents（Python SDK）、Agno、AWS Strands、MCP 协议。

5. 自定义 Span（添加业务维度）

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-business-flow") as span:
    span.set_attribute("user.tier", "premium")
    span.set_attribute("request.id", request_id)
    # 业务逻辑...

典型适用场景

场景 OpenLLMetry 能做什么
RAG 应用调试 看到每轮检索到了哪些 chunk、Token 消耗、最终答案质量
多模型切换对比 同一 Trace 对比 GPT-4o vs Claude-3.5 的响应质量和延迟
生产问题排查 某一用户请求的全链路耗时分布，定位是 LLM 慢还是检索慢
成本分析 Token 消耗按用户/时间段统计，估算 LLM 成本
Prompt 版本管理 不同 prompt 版本的 trace 对比（配合 A/B 测试框架）
多 Agent 协作追踪 CrewAI / LangGraph 多 Agent 协作中，每个 Agent 的调用链路

坑与注意

  1. v0.49.2 以下版本有隐式遥测：早期版本会收集少量匿名遥测数据用于异常检测，v0.49.2+ 已移除。如果用的是旧版本请升级。
  2. 生产环境采样率：全量追踪会产生大量数据，生产环境建议配置采样策略（Traceloop.init(sampler=...)），不要盲目全开。
  3. Token 计数精度：Token 计数基于 LLM Provider 返回值，部分 Provider 对 streaming 模式的 token 统计可能有延迟累计问题。
  4. 敏感数据脱敏：prompt 和 response 默认会记录到 trace 中，如包含用户隐私信息，需在发送前做脱敏处理，或配置敏感属性过滤。
  5. 国内访问 Traceloop 文档：官网文档（traceloop.com/docs）在部分地区可能需要访问支持，建议直接参考 GitHub README。
  6. OpenTelemetry 语义约定仍在演进：LLM 相关的 span 属性命名规范尚未完全稳定（截至 2026 年，OpenTelemetry 已将 LLM 语义约定纳入标准），但 OpenLLMetry 会跟随最新规范。

与同类对比

工具 定位 OpenLLMetry 优势 OpenLLMetry 劣势
LangSmith LangChain 官方平台 深度集成 LangChain、功能全 商业产品、有用量限制、绑定 LangChain
Phoenix (Arize) LLM 可观测性 支持多种框架、可本地部署 接入相对更多配置
Weave (Weights & Biases) ML/LLM 实验跟踪 实验管理能力强 非专为 LLM 设计，追踪功能相对薄
OpenLLMetry OpenTelemetry 标准 LLM 扩展 20+ 后端、框架覆盖广、标准协议不锁定 需要一定 OTEL 概念理解

一句话推荐结论

如果你已经在用或计划用 OpenTelemetry 生态，同时希望对 LLM 调用拥有完整的可观测性（延迟、Token 消耗、检索链路），OpenLLMetry 是目前接入最简单（两行代码）、后端支持最广（20+）、框架覆盖最全的开源方案，推荐先 pip install traceloop-sdk 体验本地 trace。