Agent 可观测性是决定一个智能体项目能否从“玩具”走向“生产级”的关键分水岭。今天我们不谈复杂的理论直接聚焦于如何为你的 Agent 系统快速搭建起一套可落地的监控体系核心就是 Tracing、Metrics 和全链路监控。无论你是在开发一个简单的任务自动化 Agent还是一个复杂的多智能体协作系统如果无法清晰地看到它的内部执行过程、性能瓶颈和错误根源那么调试和优化都将是一场噩梦。这篇文章将带你快速理解 Agent 可观测性的核心三要素并提供一套从零开始的实践方案。我们会重点关注如何为 Agent 的每一次执行生成追踪链路Tracing如何收集关键的性能指标Metrics以及如何将它们整合成全链路监控视图。整个过程会涉及开源工具选型、代码埋点、数据可视化和告警配置目标是让你在本地环境就能跑通一个具备基本可观测能力的 Agent 演示项目。如果你正在面临 Agent 执行过程像黑盒、出错难以定位、性能无法量化评估等问题那么这篇文章提供的思路和工具链将直接为你所用。我们将从最基础的日志升级开始逐步构建一个结构化的可观测性系统。1. 核心能力速览构建 Agent 可观测性体系在深入细节之前我们先通过一个表格快速了解构建 Agent 可观测性体系的核心组成部分及其价值这能帮助你判断接下来的内容是否匹配你的需求。能力项说明与目标Tracing (链路追踪)记录单个请求在 Agent 内部及外部调用如 LLM、工具、数据库的完整路径与耗时形成可视化调用链。用于定位慢查询和故障点。Metrics (指标度量)持续收集聚合数据如 Agent 调用次数、成功率、响应时间分位数、Token 消耗、工具使用频率等。用于评估性能与健康度。Logging (结构化日志)记录离散的、带上下文如 Trace ID的事件信息补充链路细节。是排查问题的原始依据。全链路监控将 Trace、Metric、Log 通过统一的标识如 Request ID关联在一个界面中还原问题现场。核心开源工具OpenTelemetry (数据采集与导出) Jaeger/Tempo (Trace 存储与查询) Prometheus (Metric 存储) Grafana (数据可视化与告警)。部署与资源门槛可在本地使用 Docker Compose 一键启动所有组件对硬件无特殊要求4GB 内存 少量磁盘空间。生产环境需考虑资源规划。代码侵入性需在 Agent 框架代码中进行埋点手动或通过框架中间件。主流 Python/Node.js/Go 的 Agent 框架已有相关SDK支持。适合场景任何需要调试、优化、监控或审计其执行过程的 Agent 系统尤其适用于复杂、多步骤或对外部服务有依赖的 Agent。2. 为什么 Agent 特别需要可观测性与传统的微服务或单体应用不同Agent 的执行流程具有更高的不确定性和复杂性这放大了对可观测性的需求。1. 动态执行路径Agent 根据 LLM 的决策动态调用不同的工具Tools或执行规划Plans每次请求的调用链可能完全不同。没有 Tracing你很难理解它“为什么”走了某条路径。2. 外部依赖众多一次 Agent 执行可能涉及多次 LLM API 调用、数据库查询、第三方服务请求。任何一环的延迟或失败都会影响最终结果需要全链路监控来定位瓶颈。3. 状态难以捕捉Agent 的“思考过程”如 Chain-of-Thought、内部状态记忆、目标是逻辑核心。通过结构化的 Log 和 Trace 将关键状态暴露出来是调试复杂逻辑的关键。4. 成本与性能监控LLM 调用成本高昂尤其是 GPT-4 等模型。Metrics 可以清晰统计 Token 消耗、调用次数帮助优化提示词和流程以降低成本。缺乏可观测性的 Agent 系统其问题通常表现为“任务失败了但不知道在哪一步”、“响应时快时慢找不到原因”、“无法量化 Agent 在不同场景下的表现”。接下来我们将通过实践解决这些问题。3. 环境准备与工具链选型我们将使用当前业界事实上的标准——OpenTelemetry (OTel)作为可观测性数据的采集和导出标准。它统一了 Tracing、Metrics、Logs 的 API并支持将数据导出到多种后端如 Jaeger, Prometheus。本地演示环境准备清单操作系统Windows (WSL2), macOS 或 Linux。本文演示基于 Linux/macOS 命令行Windows 用户可通过 WSL2 获得类似体验。Docker 与 Docker Compose这是最简单的一键启动监控后端的方式。请确保已安装。# 检查安装 docker --version docker-compose --versionPython 环境Agent 示例代码将使用 Python。建议使用 Python 3.9 和venv虚拟环境。python3 --version pip3 --version基础 Agent 框架我们将以一个简单的 LangChain Agent 为例。你需要安装langchain和openai(或其它 LLM 供应商) 包。本文重点在可观测性故不展开 Agent 具体逻辑。监控后端套件我们将通过 Docker Compose 启动一套包含以下组件的迷你监控栈Jaeger:用于接收、存储和查询 Trace 数据。Prometheus:用于抓取和存储 Metrics 数据。Grafana:用于可视化 Trace 和 Metric并设置告警。4. 一键启动监控后端 (Docker Compose)在项目根目录创建一个docker-compose.yml文件内容如下。这个配置集成了 Trace、Metric 和 Log 收集的常用组件。version: 3.8 services: # Jaeger - 用于追踪(Tracing) jaeger-all-in-one: image: jaegertracing/all-in-one:latest container_name: jaeger ports: - 16686:16686 # Jaeger UI 前端 - 14268:14268 # 接收 Jaeger 格式的 Thrift HTTP 数据 - 4318:4318 # 接收 OpenTelemetry 格式的 HTTP 数据推荐 environment: - COLLECTOR_OTLP_ENABLEDtrue # Prometheus - 用于指标(Metrics) prometheus: image: prom/prometheus:latest container_name: prometheus ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml - prom_data:/prometheus command: - --config.file/etc/prometheus/prometheus.yml - --storage.tsdb.path/prometheus - --web.console.libraries/etc/prometheus/console_libraries - --web.console.templates/etc/prometheus/consoles - --storage.tsdb.retention.time200h - --web.enable-lifecycle # Grafana - 用于可视化 grafana: image: grafana/grafana:latest container_name: grafana ports: - 3000:3000 environment: - GF_SECURITY_ADMIN_PASSWORDadmin # 设置默认密码首次登录后请修改 volumes: - grafana_data:/var/lib/grafana - ./grafana/provisioning:/etc/grafana/provisioning # 可选预配置数据源和仪表盘 volumes: prom_data: grafana_data:同时创建 Prometheus 的配置文件prometheus.ymlglobal: scrape_interval: 15s # 每15秒抓取一次指标 evaluation_interval: 15s scrape_configs: - job_name: otel-collector # 我们稍后会部署一个 OTel Collector 来接收指标 static_configs: - targets: [otel-collector:8889] - job_name: prometheus static_configs: - targets: [localhost:9090]现在在终端中执行以下命令启动所有服务docker-compose up -d启动后你可以访问以下服务Grafana:http://localhost:3000(用户名admin, 密码admin)Jaeger UI:http://localhost:16686Prometheus:http://localhost:9090至此你的监控“后台”已经就绪。接下来我们需要在 Agent 代码中“生产”可观测性数据。5. 为 Python Agent 注入可观测性 (OpenTelemetry 埋点)我们将创建一个简单的 LangChain Agent并为其添加 OpenTelemetry instrumentation。第一步安装必要的 Python 包pip install langchain-openai langchain langchain-community opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation opentelemetry-instrumentation-requests opentelemetry-instrumentation-langchainopentelemetry-*系列包是核心。opentelemetry-instrumentation-langchain是社区提供的 LangChain 自动埋点工具实验性能大大简化工作。我们也会演示手动埋点。第二步编写一个简单的可观测 Agent 示例 (observable_agent.py)import os from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_community.tools import DuckDuckGoSearchRun # 1. 初始化 OpenTelemetry from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.resources import Resource # 设置服务名这在 Jaeger 中用于区分不同服务 resource Resource(attributes{ service.name: my-ai-agent, service.version: 1.0.0, }) # 设置 TracerProvider trace.set_tracer_provider(TracerProvider(resourceresource)) # 创建 OTLP 导出器将数据发送到 Jaeger (运行在本地 4318 端口) otlp_exporter OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces) # 将导出器添加到 TracerProvider span_processor BatchSpanProcessor(otlp_exporter) trace.get_tracer_provider().add_span_processor(span_processor) # 获取一个 Tracer tracer trace.get_tracer(__name__) # 2. 可选但推荐自动 Instrumentation - 对 LangChain 和 requests 进行自动埋点 from opentelemetry.instrumentation.requests import RequestsInstrumentor from opentelemetry.instrumentation.langchain import LangchainInstrumentor RequestsInstrumentor().instrument() LangchainInstrumentor().instrument(tracer_providertrace.get_tracer_provider()) # 3. 创建 Agent 工具和模型 search_tool DuckDuckGoSearchRun() llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyos.getenv(OPENAI_API_KEY)) tools [search_tool] prompt ChatPromptTemplate.from_messages([ (system, You are a helpful assistant. Use tools when necessary.), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 4. 手动埋点示例包装整个 Agent 执行过程 def run_agent_with_tracing(user_input: str): # 使用 tracer 启动一个 span这个 span 代表一次完整的 Agent 执行 with tracer.start_as_current_span(agent_execution) as span: # 为当前 span 设置一些属性在 Jaeger 中可以看到 span.set_attribute(user.input, user_input) span.set_attribute(agent.type, tool_calling) try: print(f\n 用户输入: {user_input}) # 实际执行 Agent result agent_executor.invoke({input: user_input}) output result.get(output, No output) # 记录成功结果作为事件 span.add_event(agent.completed, attributes{output.length: len(output)}) span.set_status(trace.Status(trace.StatusCode.OK)) print(f Agent 输出: {output}) return output except Exception as e: # 记录错误 span.record_exception(e) span.set_status(trace.Status(trace.StatusCode.ERROR, str(e))) print(f!!! Agent 执行出错: {e}) raise # 5. 运行测试 if __name__ __main__: # 请确保已设置环境变量 OPENAI_API_KEY questions [ 谁是 OpenAI 的现任 CEO, 用中文总结一下什么是 Agent 可观测性。 ] for q in questions: run_agent_with_tracing(q) print(- * 50)代码关键点解析OTLP 导出器配置将追踪数据发送到本地 Jaeger 的 OTLP HTTP 端口 (4318)。自动埋点RequestsInstrumentor和LangchainInstrumentor会自动为网络请求和 LangChain 的内部操作如 LLM 调用、工具执行创建子 span极大减少了手动工作量。手动埋点我们手动创建了一个名为agent_execution的根 span包裹了整个 Agent 调用过程并添加了自定义属性如用户输入和事件如完成事件。错误处理在except块中记录异常并将 span 状态设为ERROR这对于问题排查至关重要。第三步运行并查看结果在终端设置你的 OpenAI API Key然后运行脚本export OPENAI_API_KEYyour-api-key-here # Linux/macOS # set OPENAI_API_KEYyour-api-key-here # Windows CMD python observable_agent.py脚本执行后打开浏览器访问Jaeger UI (http://localhost:16686)。在 Service 下拉菜单中选择my-ai-agent然后点击Find Traces。你应该能看到两条 Trace每条对应一次 Agent 调用。点击其中一条即可看到完整的调用链详情。在 Jaeger 中你会看到一个agent_executionspan你手动创建的根 span。其下自动生成了多个子 span例如langchain.llms.openai(LLM 调用)langchain.tools(工具执行如DuckDuckGoSearchRun)HTTP GET(由requestsinstrumentor 捕获的网络请求)每个 span 都有精确的开始/结束时间、耗时、标签如user.input和状态。如果某次工具调用或 LLM 请求特别慢你可以立即在时间轴上看到是哪个环节拖慢了整体速度。6. 收集与可视化 Metrics (指标)Tracing 解决了“哪里慢”的问题而 Metrics 则回答“整体有多慢、成功率多少”等聚合问题。我们将使用 OpenTelemetry 的 Metrics SDK 和 Prometheus 来收集 Agent 的关键指标。第一步扩展 Agent 代码以暴露 Metrics修改或创建新的文件agent_with_metrics.pyimport time import random from opentelemetry import metrics from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter from opentelemetry.sdk.resources import Resource # 1. 设置 Metrics 导出器 (发送到 OTLP Collector再由 Collector 转给 Prometheus) # 注意为了简化我们直接假设有一个 OTel Collector 在运行。更简单的做法是直接使用 Prometheus 的 Pull 模式。 # 这里我们演示 OTLP 推送模式。 resource Resource.create(attributes{service.name: my-ai-agent-metrics}) # 创建 MetricReader 和导出器 metric_exporter OTLPMetricExporter(endpointhttp://localhost:4318/v1/metrics) # 发送到 Collector metric_reader PeriodicExportingMetricReader(exportermetric_exporter, export_interval_millis5000) # 设置 MeterProvider meter_provider MeterProvider(resourceresource, metric_readers[metric_reader]) metrics.set_meter_provider(meter_provider) # 获取一个 Meter meter metrics.get_meter(__name__) # 2. 创建几个关键的 Metrics # 计数器记录 Agent 被调用的总次数 agent_invocation_counter meter.create_counter( nameagent_invocations_total, descriptionTotal number of agent invocations, unit1, ) # 直方图记录 Agent 执行的耗时分布单位秒 agent_duration_histogram meter.create_histogram( nameagent_execution_duration_seconds, descriptionDuration of agent execution in seconds, units, ) # 计数器记录按结果状态成功/失败分类的调用次数 agent_success_counter meter.create_counter( nameagent_invocations_by_status, descriptionNumber of agent invocations by status, unit1, ) # 3. 模拟一个 Agent 执行函数并记录 Metrics def simulate_agent_execution(query: str): 模拟一次 Agent 执行并记录相关指标 start_time time.time() agent_invocation_counter.add(1, attributes{query_type: general}) # 记录调用 # 模拟执行过程和可能的失败 time.sleep(random.uniform(0.5, 2.0)) # 模拟耗时 is_success random.random() 0.2 # 模拟 80% 成功率 duration time.time() - start_time agent_duration_histogram.record(duration, attributes{status: success if is_success else error}) if is_success: agent_success_counter.add(1, attributes{status: success}) print(fQuery {query} succeeded in {duration:.2f}s) else: agent_success_counter.add(1, attributes{status: error}) print(fQuery {query} failed after {duration:.2f}s) return is_success # 4. 运行模拟 if __name__ __main__: queries [What is AI?, Explain quantum computing., Tell me a joke., Fetch latest news.] for i in range(20): # 模拟 20 次调用 q random.choice(queries) simulate_agent_execution(q) time.sleep(random.uniform(0.1, 0.5)) # 保持程序运行一段时间让 Metric Reader 有机会导出数据 print(\nMetrics are being exported... (CtrlC to stop)) try: time.sleep(30) except KeyboardInterrupt: pass finally: # 清理 meter_provider.shutdown()第二步部署 OpenTelemetry Collector (简化版)为了将 OTLP Metrics 转换为 Prometheus 可抓取的格式我们需要一个 OTel Collector。创建一个otel-collector-config.yaml文件receivers: otlp: protocols: http: endpoint: 0.0.0.0:4318 exporters: prometheus: endpoint: 0.0.0.0:8889 namespace: ai_agent const_labels: source: otel processors: batch: service: pipelines: metrics: receivers: [otlp] processors: [batch] exporters: [prometheus]然后在docker-compose.yml中添加otel-collector服务otel-collector: image: otel/opentelemetry-collector-contrib:latest container_name: otel-collector command: [--config/etc/otel-collector-config.yaml] volumes: - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports: - 4318:4318 # 接收 OTLP 数据 - 8889:8889 # 暴露 Prometheus 格式的指标 depends_on: - prometheus更新prometheus.yml确保它从 Collector 抓取数据scrape_configs: - job_name: otel-collector static_configs: - targets: [otel-collector:8889] # 注意这里是容器名 - job_name: prometheus static_configs: - targets: [localhost:9090]第三步重启服务并运行 Agent停止并重启 Docker Compose 服务docker-compose down docker-compose up -d运行agent_with_metrics.py脚本。访问Prometheus (http://localhost:9090)在表达式输入框中输入ai_agent_你应该能看到一系列以ai_agent_开头的指标例如ai_agent_agent_invocations_total。访问Grafana (http://localhost:3000)添加 Prometheus 作为数据源地址为http://prometheus:9090因为它们在同一个 Docker 网络内。然后你可以创建仪表盘来可视化这些指标例如图表1rate(ai_agent_agent_invocations_total[5m])- 显示最近5分钟的平均调用速率。图表2histogram_quantile(0.95, rate(ai_agent_agent_execution_duration_seconds_bucket[5m]))- 显示95分位的执行耗时。图表3sum(rate(ai_agent_agent_invocations_by_status{statussuccess}[5m])) / sum(rate(ai_agent_agent_invocations_total[5m]))- 计算成功率。7. 关联 Logs、Traces 和 Metrics (全链路监控)真正的全链路监控在于关联。核心是通过一个唯一的Trace ID贯穿所有数据。OpenTelemetry 的 Context 传播机制可以自动做到这一点。在日志中注入 Trace ID修改你的日志记录方式确保每条日志都包含当前 Span 的 Trace ID 和 Span ID。使用opentelemetry.trace来获取当前上下文。import logging from opentelemetry import trace # 配置日志格式包含 trace_id 和 span_id log_format %(asctime)s - %(name)s - [%(trace_id)s] - [%(span_id)s] - %(levelname)s - %(message)s logging.basicConfig(levellogging.INFO, formatlog_format) class ContextFilter(logging.Filter): def filter(self, record): # 获取当前 span 的上下文 current_span trace.get_current_span() ctx current_span.get_span_context() if current_span else None if ctx and ctx.is_valid: record.trace_id format(ctx.trace_id, 032x) record.span_id format(ctx.span_id, 016x) else: record.trace_id 0 * 32 record.span_id 0 * 16 return True logger logging.getLogger(__name__) logger.addFilter(ContextFilter()) # 在 Agent 执行函数中使用 def run_agent(user_input): with tracer.start_as_current_span(agent_execution): logger.info(fStarting agent execution for input: {user_input}) # ... 执行逻辑 ... logger.info(Agent execution completed)现在当日志被集中收集例如使用 Loki并展示在 Grafana 中时你可以通过 Trace ID 直接从 Jaeger 的 Trace 详情页跳转到相关的日志行反之亦然。Grafana 的“Tempo”数据源另一个 Trace 后端或“Loki”与“Jaeger”的数据源关联功能可以很好地实现这一点。在 Grafana 中关联配置 Grafana 的数据源包括 Jaeger (Trace)、Prometheus (Metric) 和 Loki (Log)。在 Explore 页面查询一个 Trace。如果配置正确Grafana 会显示一个 “Logs for this span” 或类似按钮点击即可查看该 Trace 对应的所有日志。8. 常见问题与排查方法在搭建和使用 Agent 可观测性体系时你可能会遇到以下典型问题问题现象可能原因排查方式解决方案Jaeger UI 中看不到 Trace1. Agent 代码未正确初始化或导出 OTLP 数据。2. OTLP 导出器地址或端口错误。3. Docker 网络问题Agent 无法连接到 Jaeger。1. 检查 Agent 代码中OTLPSpanExporter的endpoint。2. 查看 Agent 运行日志确认 OTel SDK 有无报错。3. 在 Agent 容器或主机上使用curl测试http://localhost:4318/v1/traces连通性。1. 确保endpoint指向正确的 Jaeger OTLP 端口默认4318。2. 如果 Agent 运行在 Docker 内使用服务名如http://jaeger:4318而非localhost。3. 检查 Docker Compose 网络配置。Prometheus 抓不到指标1. OTel Collector 配置错误或未运行。2. Prometheus 配置中的targets地址错误。3. 指标名称前缀不匹配。1. 检查otel-collector容器日志。2. 访问http://otel-collector:8889/metrics看是否有数据。3. 在 Prometheus UI 的Targets页面查看抓取状态。1. 确认otel-collector-config.yaml中exporters.prometheus.endpoint与 Prometheus 配置的targets一致。2. 确保 Prometheus 配置中使用了正确的容器服务名和端口。Grafana 中数据源测试失败1. Grafana 容器无法访问其他服务如 Prometheus, Jaeger。2. 数据源 URL 使用了localhost在容器内指 Grafana 自己。1. 在 Grafana 容器内使用curl测试到其他服务的网络。2. 检查数据源配置中的 URL。在 Docker Compose 中Grafana 访问其他服务应使用服务名作为主机名例如http://prometheus:9090http://jaeger:16686。Trace 数据不全缺少 LLM 或工具调用的子 Span1. 对应的自动埋点库如opentelemetry-instrumentation-langchain未正确安装或初始化。2. Agent 框架版本与埋点库不兼容。1. 确认已安装并instrument()了相应的库。2. 查看 Jaeger 中已有的 Trace确认缺失的是哪部分。1. 确保在创建 Tracer 后、使用框架前调用instrument()方法。2. 查阅对应 instrumentation 库的文档确认支持的版本。考虑使用手动埋点作为补充。指标数据延迟或看不到1. OTel Metric Reader 的导出间隔 (export_interval_millis) 设置过长。2. Prometheus 的抓取间隔 (scrape_interval) 过长。1. 检查代码中PeriodicExportingMetricReader的参数。2. 检查prometheus.yml中的scrape_interval。1. 在开发环境可以适当调小导出间隔如5000毫秒。2. 注意过于频繁的导出和抓取会增加系统负载。高并发下性能开销大1. 采样率设置为 100%默认每个请求都记录 Trace。2. 记录了过多或过大的 Span 属性Attributes和事件Events。1. 使用性能分析工具监控 Agent 进程的 CPU 和内存。2. 评估 Trace 数据的体积。1. 在生产环境配置采样率如概率采样ProbabilitySampler(rate0.1)只记录一部分请求。2. 精简 Span 的属性和事件只记录关键业务信息。9. 生产环境最佳实践与建议将可观测性应用到生产环境的 Agent 系统时需要考虑更多工程化因素采样策略全量采集所有 Trace 在流量大时成本极高。应根据实际情况配置头部采样如每100个请求采样1个或尾部采样仅采样错误或慢请求。安全与隐私Trace 和 Log 中可能包含敏感信息用户输入、API密钥片段、内部数据。务必在导出前进行脱敏处理或确保监控系统有严格的访问控制。指标设计定义对业务有意义的 SLO服务等级目标指标。例如agent_success_rate、agent_p95_latency、llm_token_usage_per_request。为这些指标设置 Grafana 告警。结构化日志强制使用 JSON 等结构化格式输出日志并包含固定的字段如timestamp,level,service,trace_id,span_id,message。这便于后续的日志聚合与查询。依赖监控Agent 严重依赖外部服务LLM API、数据库、工具服务。确保这些外部依赖的健康度也被纳入监控如通过合成监控或其自身提供的指标。版本化与标签为 Metrics 和 Traces 添加版本标签如agent_versionv1.2.0这样可以在升级后对比不同版本 Agent 的性能和稳定性。成本监控将 LLM 的 Token 消耗、API 调用次数作为核心业务指标进行监控和告警防止意外成本激增。10. 总结从黑盒到白盒的 Agent 运维为 Agent 系统引入可观测性本质上是将其从一个难以捉摸的“黑盒”转变为一个透明、可度量、可调试的“白盒”。通过本文的实践你可以快速搭建起一个包含 Tracing、Metrics 和初步全链路关联的本地监控环境。最应该优先验证的步骤是确保你的 Agent 能成功向 Jaeger 发送一条完整的 Trace。这是所有可观测性工作的基础。一旦 Trace 通了后续的指标收集、日志关联和仪表盘构建都是水到渠成的事情。最容易踩的坑通常是网络配置Docker 容器间的通信、localhost与服务名的混淆、防火墙端口阻挡。务必使用docker-compose的默认网络并在配置中使用服务名进行通信。后续深入方向包括探索更复杂的采样策略、将监控数据接入云服务如 AWS X-Ray, Datadog, Sentry、为多智能体Multi-Agent系统设计跨智能体的追踪、以及利用可观测性数据驱动 Agent 的提示词Prompt优化和流程Workflow重构。将可观测性作为 Agent 开发的基础设施来建设不仅能极大提升开发调试效率更是保障其稳定、可靠、高效运行于生产环境的基石。建议将本文的配置和代码作为起点根据你的具体 Agent 框架和业务需求进行适配和扩展。