OpenLLMetry：标准化遥测

为什么需要 OpenLLMetry：LLM 调用不透明，标准遥测是解药

传统方式下，LLM 应用的可观测性面临三个断层。第一，模型调用本质是一次对外 HTTP 请求，普通 APM 只能记录网络耗时状态码，看不到 prompt、模型名、token 用量、重试与缓存命中等业务语义；第二，RAG 应用的链路横跨向量库检索、上下文拼接、模型生成多个阶段，日志分散在各组件中，排障时需要人工拼接时间线；第三，token 消耗直接对应成本，传统监控无法按模型、按用户、按服务维度自动汇总用量，成本超支往往到月底账单出来才发现。

OpenLLMetry 的解法是把「模型调用」这类 LLM 特有动作建模成带 GenAI 语义约定的 span（追踪链路中的最小工作单元），覆盖 LLM 调用、Embedding、向量库检索、框架编排步骤等场景。它提供自动插桩机制，安装对应扩展包后，只需在程序入口调用一次 Traceloop.init()，SDK 就会自动包装 LangChain、LlamaIndex、CrewAI、OpenAI 等调用，业务代码不需要做任何侵入式修改。由于整条数据链路基于 OpenTelemetry 标准，采集到的 trace 可以导出到任何兼容 OTLP 的后端，而不是被困在某个特定平台的私有格式里。

与 Langfuse、LangSmith 这类「闭环平台」相比，OpenLLMetry 的气质差异在于它只做「遥测接入层」：不自带可视化前端、不强绑定存储，数据模型遵循公共标准。这意味着它天然适合已经有 Prometheus/Grafana/Jaeger 等基础设施、看重数据主权与技术标准化的团队；而希望开箱即得现成看板与评测功能的团队，则通常选择 Langfuse 这类平台型产品。

安装与环境配置：4 步就绪

步骤一：安装 SDK 与对应插桩扩展。 基础包是 traceloop-sdk；按使用的框架选择 tracing-* 扩展。注意当前版本为 1.45.0，建议锁定版本避免与后续发布产生兼容性差异。

步骤二：配置导出目标。 使用 Traceloop Cloud 时设置 TRACELOOP_API_KEY 与 TRACELOOP_BASE_URL；自建 OTLP 后端时设置 OTEL_EXPORTER_OTLP_ENDPOINT 指向 Collector 地址，并通过 OTEL_EXPORTER_OTLP_HEADERS 携带认证信息。

步骤三：在代码入口初始化。 调用 Traceloop.init(app_name="你的应用名")，SDK 会完成 exporter 初始化和各框架自动插桩的注册。

步骤四：验证。 运行应用发起一次 LLM 调用，在 Traceloop 控制台或自建 Grafana 中查看生成的 trace。

注意：TRACELOOP_BASE_URL 与 OTEL_EXPORTER_OTLP_ENDPOINT 二选一即可，两者同时存在时以后者为准。若均未配置，SDK 没有上报目标，trace 会被静默丢弃。

# 1. 安装（以 OpenAI + LangChain 为例）pip install 'traceloop-sdk[tracing-openai]==1.45.0'pip install 'traceloop-sdk[tracing-langchain]==1.45.0' # 2. 配置环境变量（Traceloop Cloud 方式）export TRACELOOP_API_KEY=your_api_keyexport TRACELOOP_BASE_URL=https://api.traceloop.com # 自建 OTLP 后端时改用下面两行：# export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318# export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your_token # 3. 运行应用python your_app.py

快速上手：5 分钟跑通第一个 LLM 追踪

最小可用闭环是：安装扩展 → 初始化 SDK → 发起一次模型调用 → 在控制台查看 span 树。OpenAI 调用会被 openai 插桩器自动包装，你不需要手工创建或关闭 span。

1. 创建虚拟环境并安装：pip install 'traceloop-sdk[tracing-openai]==1.45.0'

2. 新建 app.py，在文件顶部 from traceloop.sdk import Traceloop 并调用 Traceloop.init(app_name="hello_llm")

3. 设置环境变量 TRACELOOP_API_KEY 和 TRACELOOP_BASE_URL

4. 运行 python app.py，脚本会发起一次 ChatCompletion 请求

5. 打开 Traceloop 控制台的 Traces 页面，找到 hello_llm 应用的 trace，展开后可见 LLM span 中包含模型名、token 用量、耗时等属性

进阶技巧：若使用 LangChain，安装 traceloop-sdk[tracing-langchain] 后同样只需 Traceloop.init()——LangChain 自动插桩默认随初始化启用，Chain 内部的检索、提示词组装、LLM 调用会自动生成子 span，无需额外代码。

from traceloop.sdk import Traceloopfrom openai import OpenAI Traceloop.init(app_name="hello_llm") client = OpenAI()response = client.chat.completions.create(    model="gpt-4o-mini",    messages=[{"role": "user", "content": "用一句话介绍 OpenTelemetry 语义约定。"}],)print(response.choices[0].message.content)

核心能力详解：3 大支柱

支柱一：GenAI 语义约定（标准化遥测）。 OpenLLMetry 依据 OpenTelemetry 的 GenAI 语义约定，为模型调用类 span 定义统一的属性命名，例如 AI 服务商、模型名、输入输出 token 用量、请求参数等。语义建模范式统一后，跨模型（GPT、Claude、Llama）、跨框架（LangChain、LlamaIndex、CrewAI）的遥测数据可以直接聚合对比，这是「标准化」三个字的核心价值。

支柱二：零代码自动插桩。 SDK 提供 tracing-openai、tracing-langchain、tracing-llamaindex、tracing-crewai、tracing-pinecone 等扩展包。安装扩展并在入口调用 Traceloop.init() 后，SDK 通过 OpenTelemetry instrumentation 机制自动包装目标框架的调用，创建对应的 span 与属性。生产代码零侵入，升级插桩能力只需升级 SDK 版本。

支柱三：OTLP 导出到任意后端。 遥测数据通过 OTLP 协议导出，目标可以是 Traceloop Cloud，也可以是自建 Collector、Grafana Tempo、Jaeger、Datadog、Honeycomb 等任何兼容 OTLP 的可观测性后端。数据模型是标准 OpenTelemetry trace，schema 对齐的 APM 可以直接消费，不存在厂商锁定。SDK 同时支持批量 span 处理器、采样等生产特性，可在高流量下控制上报开销。

生产部署与监控：从上线到运维

部署方式一：Traceloop Cloud。 注册账号后获取 API Key，设置 TRACELOOP_API_KEY 与 TRACELOOP_BASE_URL 即可。平台提供 trace 查看、token 用量聚合与成本分析、告警能力，免费额度适合中小团队快速上线，适合不想自建基础设施的场景。

部署方式二：自建 OTLP Collector。 将 OTEL_EXPORTER_OTLP_ENDPOINT 指向内部 Collector（如 Grafana Alloy/Tempo 或 Jaeger）。数据不出内网，满足金融、政企等数据合规要求；代价是需要自行维护 Collector 的容量、采样策略与存储生命周期。建议用 OTEL_RESOURCE_ATTRIBUTES 环境变量标注服务名与部署环境，便于多服务聚合检索。

可观测性要点。 默认配置下 span 不记录 prompt 与响应原文，涉及敏感数据时保持关闭，确需排查语义问题时再按服务粒度开启 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true，并配合脱敏管道。高流量服务应开启尾部采样，只保留错误与慢 span；token 用量是成本指标，接入后应建立按 app_name 维度的用量看板与预算告警。

<p class=“para-label“>避坑清单：</p><ul class=”dash-list”><li>PyPI 包名是 traceloop-sdk 而非 openllmetry，执行 pip install openllmetry 会安装失败并误导排查方向</li><li>必须配置 OTLP 导出端点或 TRACELOOP_BASE_URL，否则 trace 静默丢弃且无任何报错</li><li>SDK 与各 tracing 扩展包版本必须锁定一致，混用不同版本可能导致插桩器加载失败</li><li>生产环境默认不记录消息内容是正确行为，不要为了「看得全」盲目开启消息捕获，会造成 PII 泄露风险</li><li>LangChain 自动插桩由 Traceloop.init 自动启用，重复手动初始化 instrumentation 会产生重复 span</li></ul>

版本迭代

OpenLLMetry 由 traceloop-sdk 演进而来，2024 年完成向 OpenTelemetry GenAI 语义约定的对齐，并将插桩包按 tracing-* 命名体系重组。版本迭代节奏快，主线是扩大框架插桩覆盖面与提升生产环境稳定性。

AI 应用场景

常见误区

面试题

参考来源

• webpageTraceloop 官网托管平台入口与产品介绍