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

1.1 一个真实的故事

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

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

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

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

1.2 什么是「可观测性」？

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

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

要素 通俗解释 类比
Traces（链路追踪） 记录一个请求从头到尾经过了哪些步骤 快递包裹的物流轨迹
Metrics（指标监控） 记录系统的各种数值指标（QPS、延迟、错误率等） 汽车的仪表盘
Logs（日志） 记录系统运行过程中的详细信息 医生的病历本

1.3 AI 时代的可观测性挑战

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

  1. 调用链路复杂：一个请求可能经过多个 Agent、多次 LLM 调用、多个工具调用
  2. Token 消耗追踪：你需要知道每次 LLM 调用消耗了多少 Token，成本是多少
  3. Prompt 和响应内容：你需要看到实际发送给模型的 Prompt 和返回的内容
  4. Agent 行为分析：你需要知道 Agent 的推理过程、决策路径

这就是 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 框架的支持：

框架类型 支持的框架
LLM SDK OpenAI、Anthropic、DashScope（阿里云）、Google GenAI、Vertex AI
Agent 框架 LangChain、LangGraph、CrewAI、AgentScope、Claude Agent SDK
工具框架 LiteLLM、Mem0、MCP Python SDK
价值三：遵循 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!\"}]}]"
    }
}

让我们逐字段解读：

字段 含义
name Span 名称，这里是「chat qwen-plus」
trace_id 链路 ID，唯一标识一次完整请求
span_id Span ID，唯一标识这个操作
start_time / end_time 开始和结束时间，可计算耗时
gen_ai.operation.name 操作类型，这里是聊天（chat）
gen_ai.request.model 使用的模型名称
gen_ai.usage.input_tokens 输入 Token 数量
gen_ai.usage.output_tokens 输出 Token 数量
gen_ai.input.messages 发送给模型的完整消息
gen_ai.output.messages 模型返回的完整消息

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

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 属性
属性名 含义 示例值
gen_ai.system AI 系统名称 openai, anthropic
gen_ai.operation.name 操作类型 chat, embeddings
gen_ai.request.model 请求的模型 gpt-4, claude-3-opus
gen_ai.request.max_tokens 最大输出 Token 1024
gen_ai.request.temperature 温度参数 0.7
gen_ai.usage.input_tokens 输入 Token 数 150
gen_ai.usage.output_tokens 输出 Token 数 80
gen_ai.usage.total_tokens 总 Token 数 230

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 提供了完整的支持。

支持的操作
操作类型 Span Kind 说明
Chain CHAIN 链式调用，如 RetrievalQA
LLM / Chat LLM 大语言模型调用
Agent AGENT Agent 执行
ReAct Step STEP ReAct 推理步骤
Tool TOOL 工具调用
Retriever RETRIEVER 检索器
Reranker RERANKER 重排序器
安装与使用
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 主要做两件事：

  1. 标记 ReAct Agent：在 create_react_agent 创建的图上设置标记
  2. 传播上下文：确保 Agent 标记能在图执行过程中传播
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 兼容的平台。

支持的平台
平台 gen_ai.system 值
OpenAI openai
Azure OpenAI azure.ai.openai
Google Gemini gemini
Perplexity perplexity
DeepSeek deepseek
Groq groq
MistralAI mistral_ai
捕获消息内容

默认情况下，消息内容（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、过滤器、采样策略
  • 最佳实践：生产环境部署建议
  • 常见问题与解决方案
# 人工智能 # 开源
Logo
EazyDevelop社区

一站式 AI 云服务平台

更多推荐

cover

新手友好！基于零代码平台学生用户画像-考勤主题标签扩展与可视化分析全流程演示

avatar EazyDevelop社区

当“写代码“本身被重构：AI编程大战进入代理纪元，零代码赛道悄然卡位

从产业分析的角度，这类产品的核心价值不在于"替代专业开发"（这是不诚实的说法），而在于吃掉传统外包市场里最痛苦的那段长尾：预算不够雇团队、复杂度又不至于上ERP的小微需求——一个门店的预约系统、一个个人品牌的着陆页、一个部门级审批流。而当硅谷的独角兽们在"自研模型 vs. 依赖外部模型""消费订阅 vs. 企业合同"之间剧烈摇摆时，中国市场走出了一条更分裂、也更现实的路线：大厂用免费换规模、用云生

avatar EazyDevelop社区
cover

冰雪传奇点卡版官方网站下载官网 电脑端模拟器部署完整教程

avatar EazyDevelop社区