深入浅出 LoongSuite Python Agent：让你的 AI 应用「透明化」（上篇）

一、开篇：为什么我们需要「可观测性」？

1.1 一个真实的故事

想象一下这个场景：你开发了一个智能客服系统，用了 LangChain 框架，接入了 GPT-4 模型。上线第一天，用户反馈「回复太慢了」。你打开日志，发现：

• 用户 A 问了「今天天气怎么样」，系统花了 30 秒才回复
• 用户 B 问了「帮我订一张机票」，系统直接超时报错

你开始排查：是模型调用慢？是数据库查询慢？还是某个 Agent 的推理逻辑出了问题？日志里只有一堆 print 语句，你根本不知道问题出在哪。

这就是典型的「黑盒问题」——你的应用像一个神秘的黑盒子，你只能看到输入和输出，中间发生了什么，一无所知。

1.2 什么是「可观测性」？

「可观测性」（Observability）这个词听起来很学术，其实大白话就是：让你的应用「透明化」，你能看到它内部发生了什么。

具体来说，可观测性包含三个核心要素：

1.3 AI 时代的可观测性挑战

传统的可观测性工具（如 Jaeger、Prometheus）主要面向普通 Web 应用。但 AI 应用有其特殊性：

这就是 LoongSuite Python Agent 登场的背景。

二、认识 LoongSuite Python Agent

2.1 它是什么？

LoongSuite Python Agent 是阿里巴巴开源的一套 Python 应用可观测性工具，专门为 AI 应用设计。它是阿里巴巴统一可观测数据采集套件 LoongSuite 的 Python 组件。

用大白话说：它是一个「自动埋点」工具，帮你自动给 AI 应用加上监控，不用你手动写一堆监控代码。

2.2 LoongSuite 家族成员

LoongSuite 是一个完整的可观测性解决方案，包含多个组件：

┌─────────────────────────────────────────────────────────────┐
│ LoongSuite 家族 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ LoongCollector │ │ Python Agent │ │ Go Agent │ │
│ │ (节点级采集) │ │ (Python应用) │ │ (Go应用) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Java Agent │ │ 更多语言… │ │
│ │ (Java应用) │ │ │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘

• LoongCollector：通用节点 Agent，基于 eBPF 技术，负责日志采集、Prometheus 指标采集、网络与安全采集
• Python Agent：专门为 Python 应用设计，支持 AI 框架的自动埋点
• Go Agent：支持编译期埋点的 Golang Agent
• Java Agent：面向 Java 应用的进程 Agent

2.3 它的核心价值

为什么你需要 LoongSuite Python Agent？三个核心价值：

价值一：零代码侵入

传统方式，你需要手动在代码里加监控：

import time

def call_llm(prompt):
start_time = time.time()
try:
result = llm.invoke(prompt)
duration = time.time() – start_time
log.info(f"LLM调用耗时: {duration}秒")
return result
except Exception as e:
log.error(f"LLM调用失败: {e}")
raise

使用 LoongSuite，你只需要在启动命令前加一个前缀：

loongsuite-instrument python your_app.py

所有监控自动完成！

价值二：专为 AI 应用设计

它内置了对主流 AI 框架的支持：

价值三：遵循 OpenTelemetry 标准

OpenTelemetry 是云原生计算基金会（CNCF）的可观测性标准。LoongSuite Python Agent 基于 OpenTelemetry 构建，这意味着：

• 你可以用任何支持 OpenTelemetry 的后端（Jaeger、Zipkin、商业 APM 等）
• 数据格式标准化，不会被厂商锁定
• 社区生态丰富

三、核心概念详解

3.1 什么是「埋点」（Instrumentation）？

「埋点」这个词来自数据分析领域，意思是「在代码的关键位置埋下数据采集点」。

举个例子，假设你有一个函数：

def process_order(order_id):
order = get_order(order_id) # 获取订单
payment = process_payment(order) # 处理支付
notify_user(order.user_id) # 通知用户
return "success"

埋点后，每个步骤都会被记录：

process_order (总耗时: 2.5s)
├── get_order (耗时: 0.1s)
├── process_payment (耗时: 2.3s) ← 这里有性能问题！
└── notify_user (耗时: 0.1s)

3.2 OpenTelemetry 的核心概念

LoongSuite Python Agent 基于 OpenTelemetry，理解几个核心概念很重要：

Span（跨度）

Span 是追踪的基本单位，代表一个操作。每个 Span 包含：

• 操作名称：比如 chat gpt-4
• 开始时间和结束时间：计算耗时
• 属性（Attributes）：比如 gen_ai.request.model = "gpt-4"
• 事件（Events）：操作过程中的关键事件
• 状态（Status）：成功还是失败

Trace（链路）

Trace 由多个 Span 组成，代表一个完整的请求链路。比如一个 AI Agent 的调用：

Trace: 用户提问「今天天气怎么样」
│
├── Span: Agent 接收请求
│ ├── Span: 调用 LLM (思考)
│ ├── Span: 调用天气 API 工具
│ ├── Span: 调用 LLM (生成回复)
│ └── Span: 返回结果给用户

Context Propagation（上下文传播）

当一个请求跨越多个服务时，上下文传播确保 Trace ID 能够传递下去，形成完整的调用链。

3.3 LoongSuite 的架构设计

LoongSuite Python Agent 采用分层架构：

┌─────────────────────────────────────────────────────────────┐
│ 你的 AI 应用 │
│ (LangChain / CrewAI / OpenAI SDK / …) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LoongSuite Instrumentation Layer │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ LangChain │ │ CrewAI │ │ OpenAI │ … │
│ │ Instrumentor │ │ Instrumentor │ │ Instrumentor │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ OpenTelemetry SDK │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tracer │ │ MeterProvider│ │ LoggerProvider│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Exporters │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ OTLP Exporter│ │ Console │ │ Jaeger │ … │
│ │ │ │ Exporter │ │ Exporter │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 后端存储与可视化 │
│ (Jaeger / Prometheus / 商业 APM / …) │
└─────────────────────────────────────────────────────────────┘

3.4 三种 Instrumentation 类型

LoongSuite Python Agent 提供三种类型的埋点：

类型一：LoongSuite Instrumentation

这是 LoongSuite 特有的埋点，专门为 AI Agent 框架设计，源码位于 instrumentation-loongsuite/ 目录。

支持的框架包括：

• AgentScope：阿里开源的多智能体框架
• CrewAI：流行的多 Agent 协作框架
• LangChain：最流行的 LLM 应用开发框架
• LangGraph：LangChain 的图编排框架
• DashScope：阿里云的 AI 服务 SDK
• LiteLLM：统一的 LLM 调用网关
• Mem0：AI 记忆管理框架
• 等等…

类型二：GenAI Instrumentation

这是遵循 OpenTelemetry 生成式 AI 语义约定的埋点，源码位于 instrumentation-genai/ 目录。

支持的框架包括：

• OpenAI：官方 OpenAI SDK
• Anthropic：Claude 的官方 SDK
• Google GenAI：Google 的生成式 AI SDK
• Vertex AI：Google Cloud 的 AI 平台
• Weaviate：向量数据库
• 等等…

类型三：通用 Instrumentation

这是通用的应用埋点，覆盖 Web 框架、数据库、消息队列等，源码位于 instrumentation/ 目录。

支持的框架包括：

• Web 框架：Flask、Django、FastAPI、Starlette…
• 数据库：MySQL、PostgreSQL、Redis、MongoDB…
• 消息队列：Kafka、RabbitMQ、Celery…
• HTTP 客户端：Requests、HTTPX、AIOHTTP…
• 等等…

四、快速上手：5 分钟体验

4.1 环境准备

首先，你需要：

• Python 3.9 或更高版本
• pip 包管理器

4.2 安装 LoongSuite Distro

pip install loongsuite-distro

这个命令会安装 LoongSuite 的核心组件，包括：

• loongsuite-instrument 命令行工具
• loongsuite-bootstrap 自动安装工具

4.3 安装具体的 Instrumentation

有三种安装方式：

方式 A：安装全部组件

loongsuite-bootstrap -a install –latest

这会安装所有支持的埋点组件。适合初次体验，但可能会安装一些你不需要的包。

方式 B：自动探测安装

loongsuite-bootstrap -a install –latest –auto-detect

这会扫描你的环境，只安装你当前项目用到的埋点。推荐用于生产环境。

方式 C：手动安装

pip install loongsuite-instrumentation-langchain
pip install loongsuite-instrumentation-openai

手动安装你需要的组件，最精细的控制。

4.4 第一个示例：监控 LangChain 应用

假设你有一个简单的 LangChain 应用：

from langchain_core.messages import HumanMessage, SystemMessage
from langchain_openai import ChatOpenAI
import os

chatLLM = ChatOpenAI(
model="qwen-plus",
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
temperature=0,
)

messages = [
SystemMessage(content="You are a helpful assistant."),
HumanMessage(content="Hello, how are you?"),
]

res = chatLLM.invoke(messages)
print(res)

使用 LoongSuite 启动：

export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

loongsuite-instrument \\
–traces_exporter console \\
–metrics_exporter console \\
–logs_exporter none \\
python demo.py

4.5 理解输出结果

运行后，你会看到类似这样的 JSON 输出：

{
"name": "chat qwen-plus",
"context": {
"trace_id": "0x153d9f32aeaef815a7ddc9ec406ef8fc",
"span_id": "0xc0c4107603054139"
},
"kind": "SpanKind.CLIENT",
"start_time": "2026-03-10T06:04:56.411044Z",
"end_time": "2026-03-10T06:04:57.205725Z",
"attributes": {
"gen_ai.operation.name": "chat",
"gen_ai.span.kind": "LLM",
"gen_ai.request.model": "qwen-plus",
"gen_ai.usage.input_tokens": 36,
"gen_ai.usage.output_tokens": 8,
"gen_ai.usage.total_tokens": 44,
"gen_ai.input.messages": "[{\\"role\\":\\"system\\",\\"parts\\":[{\\"content\\":\\"You are a helpful assistant.\\"}]},{\\"role\\":\\"user\\",\\"parts\\":[{\\"content\\":\\"Hello, how are you?\\"}]}]",
"gen_ai.output.messages": "[{\\"role\\":\\"assistant\\",\\"parts\\":[{\\"content\\":\\"I'm doing well, thank you!\\"}]}]"
}
}

让我们逐字段解读：

五、深入理解：它是如何工作的？

5.1 自动埋点的魔法

你可能会好奇：为什么加一个命令前缀就能自动监控？原理是什么？

答案是：Python 的动态特性 + wrapt 库。

wrapt 库简介

wrapt 是一个 Python 装饰器库，可以在不修改原始代码的情况下，给函数添加额外行为。

简单示例：

import wrapt

def log_wrapper(wrapped, instance, args, kwargs):
print(f"调用函数: {wrapped.__name__}")
result = wrapped(*args, **kwargs)
print(f"函数返回: {result}")
return result

@wrapt.decorator
def my_decorator(wrapped, instance, args, kwargs):
return log_wrapper(wrapped, instance, args, kwargs)

@my_decorator
def say_hello(name):
return f"Hello, {name}!"

say_hello("World")

输出：

调用函数: say_hello
函数返回: Hello, World!

LoongSuite 的实现方式

LoongSuite 使用 wrapt 在运行时「包装」目标库的函数。以 LangChain 为例：

import wrapt

def instrument_langchain():
wrapt.wrap_function_wrapper(
'langchain_core.language_models.chat_models',
'BaseChatModel.invoke',
trace_wrapper
)

def trace_wrapper(wrapped, instance, args, kwargs):
with tracer.start_as_current_span("chat") as span:
span.set_attribute("gen_ai.operation.name", "chat")
span.set_attribute("gen_ai.request.model", instance.model_name)
result = wrapped(*args, **kwargs)
span.set_attribute("gen_ai.usage.total_tokens", result.usage_metadata["total_tokens"])
return result

5.2 语义约定（Semantic Conventions）

OpenTelemetry 定义了一套标准化的属性命名规范，叫做「语义约定」。LoongSuite 遵循最新的 GenAI 语义约定。

常见的 GenAI 属性

5.3 Span 层级结构

对于复杂的 AI Agent 应用，Span 会形成层级结构。以 LangChain 的 ReAct Agent 为例：

Agent: 执行用户任务
│
├── ReAct Step 1: 第一步推理
│ ├── LLM Call: 思考下一步行动
│ └── Tool Call: 执行搜索工具
│
├── ReAct Step 2: 第二步推理
│ ├── LLM Call: 分析搜索结果
│ └── Tool Call: 执行计算工具
│
└── ReAct Step 3: 最终回答
└── LLM Call: 生成最终答案

这种层级结构让你能清晰地看到 Agent 的推理过程。

六、支持的框架详解

6.1 LangChain Instrumentation

LangChain 是最流行的 LLM 应用开发框架，LoongSuite 提供了完整的支持。

支持的操作

安装与使用

pip install loongsuite-distro
pip install loongsuite-instrumentation-langchain

from opentelemetry.instrumentation.langchain import LangChainInstrumentor
LangChainInstrumentor().instrument()

6.2 LangGraph Instrumentation

LangGraph 是 LangChain 的图编排框架，用于构建复杂的 Agent 工作流。

工作原理

LangGraph instrumentation 主要做两件事：

graph._loongsuite_react_agent = True
│
▼
Pregel.stream() 拦截调用
│
▼
注入 metadata 到 config
│
▼
LangChain callback 读取 metadata
│
▼
创建正确的 Agent Span

安装与使用

pip install loongsuite-instrumentation-langgraph

from opentelemetry.instrumentation.langgraph import LangGraphInstrumentor
LangGraphInstrumentor().instrument()

6.3 CrewAI Instrumentation

CrewAI 是一个多 Agent 协作框架，让多个 AI Agent 像团队一样工作。

示例代码

from opentelemetry.instrumentation.crewai import CrewAIInstrumentor
CrewAIInstrumentor().instrument()

from crewai import Agent, Task, Crew

agent = Agent(
role='Data Analyst',
goal='Extract actionable insights',
backstory='Expert in data analysis',
verbose=True
)

task = Task(
description='Analyze the latest AI trends',
agent=agent
)

crew = Crew(
agents=[agent],
tasks=[task],
verbose=True
)

result = crew.kickoff()

6.4 OpenAI Instrumentation

OpenAI SDK 是最基础的 LLM 调用库，支持 OpenAI 兼容的平台。

支持的平台

捕获消息内容

默认情况下，消息内容（Prompt 和 Completion）不会被捕获。要启用，设置环境变量：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

可选值：

• true：传统模式，捕获到事件
• SPAN_ONLY：捕获到 Span 属性
• EVENT_ONLY：捕获到事件属性
• SPAN_AND_EVENT：同时捕获到 Span 和事件

七、数据导出与可视化

7.1 导出到控制台

最简单的方式是输出到控制台，适合开发调试：

loongsuite-instrument \\
–traces_exporter console \\
–metrics_exporter console \\
python your_app.py

7.2 导出到 Jaeger

Jaeger 是最流行的开源分布式追踪系统。

启动 Jaeger

docker run -d –name jaeger \\
-p 16686:16686 \\
-p 4318:4318 \\
jaegertracing/all-in-one:latest

配置导出

export OTEL_SERVICE_NAME=my-ai-app
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

loongsuite-instrument python your_app.py

查看结果

打开浏览器访问 http://localhost:16686，你就能看到漂亮的追踪界面。

7.3 导出到阿里云 ARMS

如果你使用阿里云，可以导出到 ARMS（应用实时监控服务）：

export OTEL_SERVICE_NAME=my-ai-app
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=<your-arms-endpoint>
export OTEL_EXPORTER_OTLP_HEADERS="Authentication=<your-auth-token>"

loongsuite-instrument python your_app.py

（上篇完，请继续阅读下篇）

下篇将涵盖：

• 实战案例：构建一个完整的可观测 AI Agent
• 高级用法：自定义 Span、过滤器、采样策略
• 最佳实践：生产环境部署建议
• 常见问题与解决方案