Marico's space

零代码搞定 AI 可观测性：LoongSuite Python Agent 体验

前端技术 2026-04-20 17:37:18 8

译者前言：最近在折腾 AI 应用的调试问题——多 agent 流水线跑起来之后出了问题根本不知道是哪一步出的幺蛾子。OpenTelemetry 知道，但用起来门槛不低。这篇文章介绍了一个阿里云开源的工具 LoongSuite，不用改代码就能给 AI 应用加上完整的可观测性。看了一下还挺有意思，顺手翻了一下。

随着 AI 应用变得越来越复杂，很多人都会有这种感觉：功能跑起来了，但改起来越来越心虚。多 agent 流水线、工具调用、RAG（检索增强生成）、记忆等功能全上来了，问题开始冒出来：那次运行中到底发生了什么？上下文什么时候变的？哪一步把延迟拉高的？一个回复花了多少钱？更头大的是，这些操作大多发生在模型的黑盒里，团队根本没有可见性，调试也无从下手。

LoongSuite Python Agent 解决的问题就是：不用改任何业务代码，给 AI 应用加上完整的可观测性。追踪每个请求的完整链路：调了哪个模型、调了哪些工具、检索了哪些文档、消耗了多少 token、每一步上下文怎么演变的，全部清清楚楚。

AI 应用可观测性的三大核心挑战

传统微服务可观测性关注的是性能和可用性，AI 应用需要更多——目标是让运行时上下文和行为可追踪、可重现、可分析。实践中三个挑战是绕不开的。

1.1 收集运行时数据，但不影响性能

在传统微服务里代码是核心资产。但在 AI 应用中，真正重要的是运行时的数据：对话、工具调用、检索结果、内存读写，以及图像、音频、视频等多模态输入输出。这些运行时数据才指导 agent 和模型的优化方向——让你的 agent 越用越聪明。

把这些数据完整收集起来，又不影响流水线速度、不断应用——说起来容易做起来难：

● 上下文管理是动态的。可能在框架内部变化，也可能由业务逻辑控制。要在框架内部和应用代码之间透明地捕捉这些变化，需要一种非侵入式的方法。

● 多模态负载很大。把图片或音频直接塞进追踪流水线，可能成为整个系统的瓶颈。需要单独提取和存储，但不能阻塞应用。

1.2 数据语义不一致，可观测性大打折扣

收集工具一大堆——OpenTelemetry、OpenInference、Langfuse，有些框架（如 AgentScope、LangChain）自己也生成可观测性数据。但每个来源用的命名约定、属性、语义都不一样，数据收集来了根本不好用：

● 存储复用失效。不同的可观测性后端支持不同的数据协议，一个工具收的数据可能无法被另一个正确处理和存储。

● 消费逻辑无法共享。即便工具都支持同一个协议（如 OTLP），语义差异依然存在。同一个指标在不同工具里可能名字和标签都不一样，跨平台显示和处理就不可靠了。

这就把开发者绑死在了特定的可观测性后端和收集工具上。如果某个工具不支持你用的框架，就得手动实现后端的语义规范——成本高，还容易出错。

OpenTelemetry GenAI SIG（背后有几十家云、AI 和可观测性供应商支持）制定了 AI 应用可观测性的通用语义规范，定义了在关键 GenAI 交互中要收集什么、怎么命名、用什么形式。像 Langfuse、Arize 这样的平台已经采用了这套标准，把可观测性后端和收集工具解耦了。一旦数据符合 GenAI 规范，后续的可视化、消费和迭代都会顺畅很多。不过正确实现这套规范本身还是有门槛的，需要更好的工具。

1.3 端到端追踪：进程内可见性不够用

在生产环境中，agent 和工具服务经常分布在多个进程和服务。仅观察进程内的 LLM 调用会留下关键空白：追踪无法连接，延迟归因变模糊，完整的请求路径根本看不见。有意义的故障排查和优化需要在整个链路上实现端到端可见性。

单一框架的可观测性满足不了这个需求。对跨进程通信组件——如 MCP（Model Context Protocol）、A2A（Agent-to-Agent）、httpx、Flask 等——的支持，对闭合这个环路至关重要。

LoongSuite Python Agent：解决所有三个挑战

LoongSuite Python Agent 是阿里云开源的 OpenTelemetry Python Agent 分发版，专为让 AI 应用可观测性更快落地、更实用而设计。它与上游标准保持兼容，同时结合了生产验证的最佳实践，并将改进回馈给社区。

怎么工作的

基于 OpenTelemetry 标准，LoongSuite Python Agent 自动对 AI 应用进行插桩（instrumentation），无需修改任何业务代码。只需包装一下启动命令，剩下的交给他：

● 自动发现——根据你环境中的库（如 DashScope、LangChain、Flask）自动检测并加载对应插桩。
● 统一语义——所有数据符合 OpenTelemetry GenAI 语义惯例，下游可视化和消费无需重复适配。
● 全栈覆盖——同时对 AI 交互（LLM、agent、工具、RAG、记忆）和微服务调用（HTTP、gRPC、数据库）进行插桩——这是端到端可观测性的基础。
● 灵活导出——通过 OTLP 导出到任何兼容后端，包括 Jaeger、Langfuse、阿里云可观测性等。

三步入门

第一步，从 PyPI 安装 LoongSuite 分发版：

pip install loongsuite-distro

第二步，安装插桩包：

loongsuite-bootstrap -a install --version 0.1.0

这会把所有 AI 相关的插桩安装到环境中。使用 --auto-detect 可以只安装需要的，或者用 --whitelist 精确控制包含哪些插桩。

第三步，用引导程序启动应用：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental \
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY \
loongsuite-instrument python app.py

搞定——你的 AI 应用现在已经完全可观测了。

你能得到什么

在任何 OTLP 兼容平台上（Jaeger、Langfuse、阿里云可观测性），你可以直接看到：

● 完整追踪链——LLM 调用和微服务调用，全部在一个视图里。
● 细粒度性能指标——每次调用的延迟和错误详情。
● 完整上下文记录——在关键步骤捕获输入输出，用于评估和下游分析。

LoongSuite 和 OpenTelemetry 的关系

LoongSuite Python Agent 是 OpenTelemetry Python Contrib 的分叉版本，保持上游兼容性的同时扩展了 GenAI 框架支持，并更快地响应国内生态的需求。

为什么单独发版？

上游 OTel 框架矩阵对国内生态覆盖有限，LoongSuite 补充了 DashScope、AgentScope、Dify、MCP、Mem0 等的插桩支持。

上游 opentelemetry-util-genai 开发速度慢，很多功能还没到生产可用状态。LoongSuite 扩展了它：增加了多模态上传支持、额外的 span 类型和更新的语义规范。

阿里云商业部署还沉淀了一些有价值的实践，比如 ReAct 轮次级可视化和评估、会话级追踪自动关联等。

通过独立发布节奏，LoongSuite 通过 loongsuite-distro 命令推送更新，定期与上游同步，并将下游改进回馈给 OpenTelemetry 社区。

LoongSuite GenAI Util：OTel GenAI Util 的超集

并非每个 AI agent 都是基于托管框架构建的。很多开发者走的是自定义流水线：自托管 LLM 通过 REST API 调用，手动撸 ReAct 循环，从头构建 agent 以便更灵活地控制上下文管理。这些自定义代码路径不在自动插桩的范围内，需要手动追踪。

而正确的手动追踪，远不止加几个 span 那么简单。还得考虑：正确建立父-子 span 关系、符合 GenAI 语义惯例、正确捕获异常和故障、记录指标和发出日志、使用一致的开关控制大输入输出负载的捕获、多模态数据分别处理避免膨胀追踪……

OTel GenAI SIG 为此推出了 OpenTelemetry GenAI Util，让开发者构造调用对象并填入相关字段，工具自动处理剩下的事。但上游开发缓慢，很多功能还没到生产可用状态。LoongSuite GenAI Util 在此基础上构建，提供更完整、生产级的解决方案。

多模态上传：大负载不进追踪流水线

图片、音频、视频太大，直接塞进 span 或 event 会拖慢流水线、增加存储成本。LoongSuite GenAI Util 通过异步多模态上传解决这个问题：大负载被卸载到 OSS、SLS 或本地存储，追踪中只保留 URI 引用。

PreUploader 负责检测 Base64、Blob、URI 内容，生成上传任务，把消息中的多模态部分替换为 URI 引用。Uploader 异步处理这些任务，不阻塞业务线程，支持幂等性避免重复上传。存储后端支持 file://、oss://、sls:// 等，与阿里云 OSS 和 SLS 深度集成。

快速上手

安装：

pip install loongsuite-util-genai
# 包含多模态上传支持
pip install loongsuite-util-genai[multimodal_upload]

环境配置：

export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT
export OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT=true

# 多模态上传（可选）
export OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_UPLOAD_MODE=both
export OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_STORAGE_BASE_PATH=file:///var/log/genai/multimodal

手动插桩示例：

from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.extended_types import InvokeAgentInvocation
from opentelemetry.util.genai.types import InputMessage, OutputMessage, Text

# 如果用 loongsuite-instrument 启动则不需要
from opentelemetry.instrumentation._semconv import _OpenTelemetrySemanticConventionStability
if not _OpenTelemetrySemanticConventionStability._initialized:
    _OpenTelemetrySemanticConventionStability._initialize()

# 获取遥测处理器
handler = get_extended_telemetry_handler()

# 构造 InvokeAgent 调用
invocation = InvokeAgentInvocation(
    provider="dashscope",
    request_model=request["model"],
    agent_name="OrderAgent",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="查一下订单 #101 的状态")]),
        InputMessage(role="system", parts=[Text(content="你是一个负责通过工具查询订单信息的订单经理")]),
    ]
)

with handler.invoke_agent(invocation) as invocation:
    # 执行 InvokeAgent
    # ... 调用 agent ...
    
    # 补充结果
    invocation.output_messages = [
        OutputMessage(role="assistant", parts=[Text(content="让我查一下……订单 #101 找不到，请核实订单号。")], finish_reason="stop")
    ]
    invocation.input_tokens = 15
    invocation.output_tokens = 20

结语

这次发布只是开始。路线图很清楚：快速扩展插桩覆盖跟上国内 AI 生态的发展，深挖多模态处理和 span 类型，通过 LoongSuite GenAI Util 提供更全面的能力，实现 AI 和微服务调用的统一追踪让端到端可观测性真正落地，同时保持与上游的同步并把生产验证过的实践回馈社区。

如果你在构建 AI 应用并关心可观测性，不妨试试 LoongSuite Python Agent，在 GitHub 上给个 ⭐，也欢迎加入开发者社区一起塑造 AI 时代的可观测性工具。