一、开篇为什么我们需要「可观测性」1.1 一个真实的故事想象一下这个场景你开发了一个智能客服系统用了 LangChain 框架接入了 GPT-4 模型。上线第一天用户反馈「回复太慢了」。你打开日志发现用户 A 问了「今天天气怎么样」系统花了 30 秒才回复用户 B 问了「帮我订一张机票」系统直接超时报错你开始排查是模型调用慢是数据库查询慢还是某个 Agent 的推理逻辑出了问题日志里只有一堆print语句你根本不知道问题出在哪。这就是典型的「黑盒问题」——你的应用像一个神秘的黑盒子你只能看到输入和输出中间发生了什么一无所知。1.2 什么是「可观测性」「可观测性」Observability这个词听起来很学术其实大白话就是让你的应用「透明化」你能看到它内部发生了什么。具体来说可观测性包含三个核心要素要素通俗解释类比Traces链路追踪记录一个请求从头到尾经过了哪些步骤快递包裹的物流轨迹Metrics指标监控记录系统的各种数值指标QPS、延迟、错误率等汽车的仪表盘Logs日志记录系统运行过程中的详细信息医生的病历本1.3 AI 时代的可观测性挑战传统的可观测性工具如 Jaeger、Prometheus主要面向普通 Web 应用。但 AI 应用有其特殊性调用链路复杂一个请求可能经过多个 Agent、多次 LLM 调用、多个工具调用Token 消耗追踪你需要知道每次 LLM 调用消耗了多少 Token成本是多少Prompt 和响应内容你需要看到实际发送给模型的 Prompt 和返回的内容Agent 行为分析你需要知道 Agent 的推理过程、决策路径这就是LoongSuite Python Agent登场的背景。二、认识 LoongSuite Python Agent2.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 AgentJava Agent面向 Java 应用的进程 Agent2.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(fLLM调用耗时: {duration}秒) return result except Exception as e: log.error(fLLM调用失败: {e}) raise使用 LoongSuite你只需要在启动命令前加一个前缀loongsuite-instrument python your_app.py所有监控自动完成价值二专为 AI 应用设计它内置了对主流 AI 框架的支持框架类型支持的框架LLM SDKOpenAI、Anthropic、DashScope阿里云、Google GenAI、Vertex AIAgent 框架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 应用开发框架LangGraphLangChain 的图编排框架DashScope阿里云的 AI 服务 SDKLiteLLM统一的 LLM 调用网关Mem0AI 记忆管理框架等等...类型二GenAI Instrumentation这是遵循 OpenTelemetry 生成式 AI 语义约定的埋点源码位于instrumentation-genai/目录。支持的框架包括OpenAI官方 OpenAI SDKAnthropicClaude 的官方 SDKGoogle GenAIGoogle 的生成式 AI SDKVertex AIGoogle 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 Distropip 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( modelqwen-plus, base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1, api_keyos.environ.get(DASHSCOPE_API_KEY, ), temperature0, ) messages [ SystemMessage(contentYou are a helpful assistant.), HumanMessage(contentHello, how are you?), ] res chatLLM.invoke(messages) print(res)使用 LoongSuite 启动export OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTSPAN_ONLY loongsuite-instrument \ --traces_exporter console \ --metrics_exporter console \ --logs_exporter none \ python demo.py4.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\:\Im doing well, thank you!\}]}] } }让我们逐字段解读字段含义nameSpan 名称这里是「chat qwen-plus」trace_id链路 ID唯一标识一次完整请求span_idSpan ID唯一标识这个操作start_time/end_time开始和结束时间可计算耗时gen_ai.operation.name操作类型这里是聊天chatgen_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 fHello, {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 result5.2 语义约定Semantic ConventionsOpenTelemetry 定义了一套标准化的属性命名规范叫做「语义约定」。LoongSuite 遵循最新的 GenAI 语义约定。常见的 GenAI 属性属性名含义示例值gen_ai.systemAI 系统名称openai,anthropicgen_ai.operation.name操作类型chat,embeddingsgen_ai.request.model请求的模型gpt-4,claude-3-opusgen_ai.request.max_tokens最大输出 Token1024gen_ai.request.temperature温度参数0.7gen_ai.usage.input_tokens输入 Token 数150gen_ai.usage.output_tokens输出 Token 数80gen_ai.usage.total_tokens总 Token 数2305.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 InstrumentationLangChain 是最流行的 LLM 应用开发框架LoongSuite 提供了完整的支持。支持的操作操作类型Span Kind说明ChainCHAIN链式调用如 RetrievalQALLM / ChatLLM大语言模型调用AgentAGENTAgent 执行ReAct StepSTEPReAct 推理步骤ToolTOOL工具调用RetrieverRETRIEVER检索器RerankerRERANKER重排序器安装与使用pip install loongsuite-distro pip install loongsuite-instrumentation-langchainfrom opentelemetry.instrumentation.langchain import LangChainInstrumentor LangChainInstrumentor().instrument()6.2 LangGraph InstrumentationLangGraph 是 LangChain 的图编排框架用于构建复杂的 Agent 工作流。工作原理LangGraph instrumentation 主要做两件事标记 ReAct Agent在create_react_agent创建的图上设置标记传播上下文确保 Agent 标记能在图执行过程中传播graph._loongsuite_react_agent True │ ▼ Pregel.stream() 拦截调用 │ ▼ 注入 metadata 到 config │ ▼ LangChain callback 读取 metadata │ ▼ 创建正确的 Agent Span安装与使用pip install loongsuite-instrumentation-langgraphfrom opentelemetry.instrumentation.langgraph import LangGraphInstrumentor LangGraphInstrumentor().instrument()6.3 CrewAI InstrumentationCrewAI 是一个多 Agent 协作框架让多个 AI Agent 像团队一样工作。示例代码from opentelemetry.instrumentation.crewai import CrewAIInstrumentor CrewAIInstrumentor().instrument() from crewai import Agent, Task, Crew agent Agent( roleData Analyst, goalExtract actionable insights, backstoryExpert in data analysis, verboseTrue ) task Task( descriptionAnalyze the latest AI trends, agentagent ) crew Crew( agents[agent], tasks[task], verboseTrue ) result crew.kickoff()6.4 OpenAI InstrumentationOpenAI SDK 是最基础的 LLM 调用库支持 OpenAI 兼容的平台。支持的平台平台gen_ai.system 值OpenAIopenaiAzure OpenAIazure.ai.openaiGoogle GeminigeminiPerplexityperplexityDeepSeekdeepseekGroqgroqMistralAImistral_ai捕获消息内容默认情况下消息内容Prompt 和 Completion不会被捕获。要启用设置环境变量export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTSPAN_ONLY可选值true传统模式捕获到事件SPAN_ONLY捕获到 Span 属性EVENT_ONLY捕获到事件属性SPAN_AND_EVENT同时捕获到 Span 和事件七、数据导出与可视化7.1 导出到控制台最简单的方式是输出到控制台适合开发调试loongsuite-instrument \ --traces_exporter console \ --metrics_exporter console \ python your_app.py7.2 导出到 JaegerJaeger 是最流行的开源分布式追踪系统。启动 Jaegerdocker run -d --name jaeger \ -p 16686:16686 \ -p 4318:4318 \ jaegertracing/all-in-one:latest配置导出export OTEL_SERVICE_NAMEmy-ai-app export OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf export OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4318/v1/traces loongsuite-instrument python your_app.py查看结果打开浏览器访问http://localhost:16686你就能看到漂亮的追踪界面。7.3 导出到阿里云 ARMS如果你使用阿里云可以导出到 ARMS应用实时监控服务export OTEL_SERVICE_NAMEmy-ai-app export OTEL_EXPORTER_OTLP_PROTOCOLgrpc export OTEL_EXPORTER_OTLP_ENDPOINTyour-arms-endpoint export OTEL_EXPORTER_OTLP_HEADERSAuthenticationyour-auth-token loongsuite-instrument python your_app.py上篇完请继续阅读下篇下篇将涵盖实战案例构建一个完整的可观测 AI Agent高级用法自定义 Span、过滤器、采样策略最佳实践生产环境部署建议常见问题与解决方案