LlamaIndex 的可观测性与监控(基于 OpenTelemetry)
本指南将带你完成基于 Python 的 LlamaIndex 应用的观测性与监控配置,并通过 OpenTelemetry 将遥测数据流式传输至 SigNoz Cloud。完成设置后,你将能够监控 LlamaIndex 中特定的 AI 操作,例如文档摄取、文档检索、用户查询、文本生成和用户反馈,同时通过详细的 span 捕获请求时长、节点与查询输入、模型输出、检索评分、元数据以及管道中的中间步骤。
通过为 RAG 工作流添加遥测探针,你可以实现检索和生成管道的全链路可观测性。这在构建生产级、面向开发者的工具时尤为关键,因为洞察模型行为、延迟瓶颈和检索准确率至关重要。借助 SigNoz,你可以端到端地追踪每个用户问题,从提示词到响应,并持续优化性能和可靠性。
如需快速上手,请参考我们示例 LlamaIndex RAG 问答机器人,该示例集成了基于 OpenInference 的 OpenTelemetry 监控。你可以在这里查看完整代码仓库 here。
先决条件
- 一个使用 Python 3.8+ 的应用程序
- 已在应用中集成 LlamaIndex,并配置好文档摄取和查询接口
- 对 RAG(检索增强生成)工作流有基本了解
- SigNoz 环境配置(二选一):
- 拥有活跃摄取密钥的 SigNoz Cloud 账户
- 自托管的 SigNoz 实例
- 已安装
pip以管理 Python 包 - 具备互联网连接,以便向 SigNoz Cloud 发送遥测数据
- (可选但推荐) 创建一个 Python 虚拟环境以隔离依赖关系
为 LlamaIndex 应用添加探针
为了在不修改核心应用逻辑的情况下从 LlamaIndex 捕获详细遥测数据,我们采用 OpenInference。这是一个由社区驱动的标准,基于 OpenTelemetry 构建,为 LlamaIndex 等流行 AI 框架提供预构建的探针功能。这允许你以最少配置即可追踪 LlamaIndex 应用。
如何在你这里设置 OpenInference 埋点 LlamaIndex 应用的详细说明,请查看这里。
无需代码(推荐)代码无代码自动埋点适合快速上手,只需极少代码改动。如果你不想修改应用代码、并且使用的是标准 instrumentor 库,这是获取可观测性能力的理想方式。
步骤 1:在 Python 环境中安装必要的包。
复制pip install \
opentelemetry-distro \
opentelemetry-exporter-otlp \
opentelemetry-instrumentation-httpx \
opentelemetry-instrumentation-system-metrics \
llama-index \
openinference-instrumentation-llama-index步骤 2:添加自动埋点
复制opentelemetry-bootstrap --action=install步骤 3:配置日志级别
为确保日志能被正确采集和导出,需将 root logger 配置为输出 INFO 及以上级别的日志:
复制import logging
logging.getLogger().setLevel(logging.INFO)这会把 root logger 的最低日志级别设为 INFO,确保 logger.info() 调用以及更高级别的日志(WARNING、ERROR、CRITICAL)能被 OpenTelemetry 日志自动埋点捕获并发送到 SigNoz。
步骤 4:运行示例
复制from llama_index.llms.openai import OpenAI
llm = OpenAI(model="gpt-4o")
response = llm.complete("Hello, world!")
print(response)📌 注意:运行代码前,请确保已正确设置
OPENAI_API_KEY环境变量,填入你的 API key。
步骤 5:以自动埋点方式运行应用
复制OTEL_RESOURCE_ATTRIBUTES="service.name=<service_name>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_PYTHON_LOG_CORRELATION=true \
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true \
opentelemetry-instrument <your_run_command>
<service_name>:你的服务名称<region>:你的 SigNoz Cloud 区域<your-ingestion-key>:你的 SigNoz 采集密钥- 将
<your_run_command>替换为实际运行应用程序的命令。例如:python main.py
使用自托管 SigNoz?大多数步骤相同。若要适配本指南,请按照云端到自托管所述,更新端点并移除采集密钥头部。
基于代码的埋点为你提供对遥测配置的细粒度控制。当你需要自定义资源属性、采样策略,或与现有的可观测性基础设施集成时,请使用此方法。
步骤 1:安装 OpenInference 和 OpenTelemetry 相关包
Copypip install openinference-instrumentation-llama-index \
opentelemetry-exporter-otlp \
opentelemetry-sdk \
llama-index步骤 2:在 Python 应用程序中导入必要的模块
Copyfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor步骤 3:配置 OpenTelemetry Tracer Provider,以将 trace 直接发送到 SigNoz Cloud
Copyresource = Resource.create({"service.name": "<service_name>"})
provider = TracerProvider(resource=resource)
span_exporter = OTLPSpanExporter(
endpoint="https://ingest.<region>.signoz.cloud:443/v1/traces",
headers={"signoz-ingestion-key": "<your-ingestion-key>"},
)
provider.add_span_processor(BatchSpanProcessor(span_exporter))<service_name>:你的服务名称<region>:你的 SigNoz Cloud 区域<your-ingestion-key>:你的 SigNoz ingestion key
使用自托管 SigNoz?大部分步骤完全相同。只需参考 Cloud → Self-Hosted 文档,修改 endpoint 并移除 ingestion key 请求头即可。
第 4 步:使用 OpenInference 和配置好的 Tracer Provider 对 LlamaIndex 进行插桩
使用 OpenInference 提供的 LlamaIndexInstrumentor,即可在你的 OpenTelemetry 配置下自动追踪 LlamaIndex 的各项操作:
LlamaIndexInstrumentor().instrument(tracer_provider=provider)📌 注意:请把这段代码放在应用逻辑的最前面——在任何 LlamaIndex 函数被调用之前——以确保遥测数据能被正确采集。
第 5 步:运行示例
Copyfrom llama_index.llms.openai import OpenAI
llm = OpenAI(model="gpt-4o")
response = llm.complete("Hello, world!")
print(response)📌 提示:运行代码前,请确保已正确设置
OPENAI_API_KEY环境变量,填入你的 API key。
现在,你的 LlamaIndex 命令会自动生成 traces、spans 和 attributes。
最后,你可以在 SigNoz Cloud 的 traces 标签页中查看这些数据:

点击 SigNoz 中的某个 trace ID,就能看到该 trace 的详细视图,包括所有关联的 spans 及其 events 和 attributes。

在 AI Observability 中查看
AI 可观测性展示了 LlamaIndex 应用中 LLM 调用的成本、Token 用量、延迟和错误。在 SigNoz 中,打开 AI 可观测性,并在 service_name 过滤器中选择你的服务。

查询单个 Trace 时,打开 Explorer 选项卡。Trace 视图为每个 Trace 显示一行,包含 Token、成本和调用次数等总计值。你可以按这些总计值进行过滤、聚合和排序,例如 trace.total_tokens > 1000。详情参见AI 可观测性 Explorer。
如果面板保持空白,请确保你的 Spans 携带了遥测要求中指定的属性。要映射其他属性名称,请使用属性映射。
相关集成
追踪你的 LLM 应用和检索堆栈的其余部分:
- 使用 OpenTelemetry 监控 Haystack 管道 - 追踪 RAG 管道、检索器和生成器节点
- 使用 OpenTelemetry 实现 DSPy 可观测性 - 追踪模块、链和优化器运行
- 使用 OpenTelemetry 实现 Vercel AI SDK 可观测性 - 在 Next.js 中追踪 generateText、streamText 和工具调用
- 使用 OpenTelemetry 监控 Firecrawl - 追踪 scrape、crawl、search 和 map 调用及信用额度使用情况
- 使用 OpenTelemetry 实现 Google ADK 可观测性 - 追踪 ADK 智能体、工具及其发起的模型调用
延伸阅读:
- Re