基于 OpenTelemetry 的 Agent 全链路追踪实战：解读 mcp-agent 的 Agent Tracing 示例

基于 OpenTelemetry 的 Agent 全链路追踪实战解读 mcp-agent 的 Agent Tracing 示例【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent在构建多工具、多服务器的 MCP Agent 时定位某次工具调用为什么慢哪个 MCP 服务器抛了错LLM 到底调用了几轮是日常排查的痛点。mcp-agent 框架内置了基于 OpenTelemetryOTEL的分布式追踪能力而 examples/tracing/agent 正是展示这一能力的最小完整示例它用一个同时挂载fetch与filesystem两个 MCP 服务器的 finder Agent演示了如何把 Agent 的所有方法调用以 Span 形式输出到控制台并可一键切换到 OTLP 导出把追踪数据发送到 Jaeger 等 Collector 进行可视化分析。读完本文你将掌握 mcp-agent 追踪体系的配置方法、运行方式、控制台输出解读以及如何将追踪数据接入 Jaeger 进行链路分析。示例概览一个带完整追踪的最小 Agent本示例的核心文件位于 examples/tracing/agentmain.py示例主程序定义一个名为finder的 Agentmcp_agent.config.yaml框架配置包含 MCP 服务器、模型与 OTEL 追踪配置mcp_agent.secrets.yaml.example密钥占位模板API Key 存放处可被 gitignorerequirements.txt依赖清单其中以mcp-agent file://../../../的形式直接链接本地仓库根目录其余依赖为anthropic与openai。该示例的运行方式极其简单在examples目录下执行uv run tracing/agent说明该命令假设你已安装 uv 目录运行若希望独立安装可参照 安装文档 先在本地完成框架安装再运行 main.py。finderAgent 的定位是同时拥有 filesystem 与 fetch 能力根据用户的请求在本地文件系统与远程 URL 之间找到最接近的匹配项并返回其 URI 与内容。它注册的指令instruction在 main.py 中定义finder_agent Agent( namefinder, instructionYou are an agent with access to the filesystem, as well as the ability to fetch URLs. Your job is to identify the closest match to a users request, make the appropriate tool calls, and return the URI and CONTENTS of the closest match., server_names[fetch, filesystem], human_input_callbackhuman_input_handler, )server_names指明该 Agent 连接的两个 MCP 服务器它们分别由uvx mcp-server-fetch抓取 URL与npx -y modelcontextprotocol/server-filesystem访问文件系统提供。配置解读OTEL 追踪的三要素示例的完整配置位于 mcp_agent.config.yaml追踪相关部分如下logger: transports: [file] level: debug progress_display: true path_settings: path_pattern: logs/mcp-agent-{unique_id}.jsonl unique_id: timestamp # Options: timestamp or session_id timestamp_format: %Y%m%d_%H%M%S mcp: servers: fetch: command: uvx args: [mcp-server-fetch] filesystem: command: npx args: [-y, modelcontextprotocol/server-filesystem] openai: default_model: gpt-4o-mini otel: enabled: true exporters: - console - file # To export to a collector, also include: # - otlp: # endpoint: http://localhost:4318/v1/traces service_name: BasicTracingAgentExampleotel配置块对应源码中 OpenTelemetrySettings 模型核心字段含义如下配置项默认值说明enabledfalse总开关置为true才启用追踪exporters[]导出器列表可同时启用多个console输出到标准输出、file写入 JSONL 文件、otlp发送到 Collector既支持字符串形式如console也支持键值映射形式如{file: {path: trace.jsonl}}同时支持历史兼容的{type: console}形式service_namemcp-agent服务名用于在追踪后端标识来源本示例设置为BasicTracingAgentExampleservice_instance_id自动生成服务实例 ID缺省时自动取会话 IDservice_version安装的mcp-agent版本服务版本号sample_rate1.0采样率1.0表示全量采样可设0~1之间的小数做比例采样值得注意的有两点其一exporters可多路并存本示例同时启用了console与file——控制台用于实时观察文件用于事后分析其二字符串形式的导出器会回退读取历史遗留字段如otlp_settings、path、path_settings这一兼容逻辑实现在 config.py 的模型校验器中。此外file导出器的文件路径由path_settings控制。对应源码中的 TracePathSettings 模型path_pattern默认为traces/mcp-agent-trace-{unique_id}.jsonl占位符{unique_id}可由unique_id字段决定替换为timestamp时间戳或session_id会话 IDtimestamp_format则指定时间戳格式默认%Y%m%d_%H%M%S。openai.default_model指定默认使用的模型本示例为gpt-4o-mini而 API Key 则放在 mcp_agent.secrets.yaml.example 所示的 secrets 文件中运行前需复制为mcp_agent.secrets.yaml并填入真实密钥openai: api_key: openai_api_key anthropic: api_key: anthropic_api_key主程序流程被追踪的 Agent 方法全演练main.py 通过asyncio.run(agent_tracing())启动整个流程其追踪对象覆盖了 Agent 几乎全部方法正好构成一份哪些操作会生成 Span的清单初始化 App 与上下文MCPApp(nameagent_tracing_example, human_input_callbackhuman_input_handler)创建应用实例其内部配置加载自mcp_agent.config.yaml/mcp_agent.secrets.yaml。这里传入的human_input_handler是一个模拟单步响应的回调直接返回HumanInputResponse使示例无需真实交互即可运行。动态注入文件系统路径context.config.mcp.servers[filesystem].args.extend([os.getcwd()])将当前工作目录追加到 filesystem 服务器参数中使 Agent 能够读取当前目录。服务器能力探测finder_agent.list_tools()列出所有工具finder_agent.get_capabilities(fetch)与get_capabilities(filesystem)分别获取两个服务器的能力描述list_prompts(fetch)/list_prompts(filesystem)列出服务器提供的 Prompt 模板get_prompt(fetch_fetch, {url: https://modelcontextprotocol.io})拉取具体 Prompt 实例。挂载 LLM 并生成文本await finder_agent.attach_llm(OpenAIAugmentedLLM)将 OpenAI 增强 LLM 挂到 Agent 上随后调用llm.generate_str(messagePrint the contents of mcp_agent.config.yaml verbatim)让模型输出配置文件原文。请求人工输入finder_agent.request_human_input(...)触发一次带timeout_seconds5与元数据的人工输入请求验证追踪对人工输入流程的覆盖。直接调用 MCP 工具finder_agent.call_tool(fetch_fetch, {url: https://modelcontextprotocol.io})绕过 LLM 直接调用 fetch 工具。切换 LLM 供应商再次attach_llm(AnthropicAugmentedLLM)把同一 Agent 切换到 Anthropic 增强 LLM并让其总结https://modelcontextprotocol.io/introduction的前两段——演示了同一个 Agent 可在运行时切换不同 LLM 后端的能力。最后程序会打印总运行时长start time.time() asyncio.run(agent_tracing()) end time.time() print(fTotal run time: {t:.2f}s)控制台 Span 输出为什么所有 Agent 方法都有追踪示例 README 指出The tracing implementation will log spans to the console for all agent methods.追踪实现会把所有 Agent 方法以 Span 形式记录到控制台。这并非偶然——mcp-agent 在框架层面对 Agent 的核心方法做了统一埋点。其实现位于 src/mcp_agent/tracing/telemetry.pyTelemetryManager.traced(...)是一个装饰器工厂自动为函数创建并管理 Span同时兼容同步与异步函数见async_wrapper/sync_wrapper发生异常时调用span.record_exception(e)并设置StatusCode.ERROR保证错误链路可被追溯record_attributes/serialize_attribute会把方法的简单参数序列化进 Span 属性长字符串会被截断到 255 个字符。以console导出器运行时终端会看到形如以下的结构化输出真实输出为 OpenTelemetry 控制台导出器的完整 JSON/结构化格式其中finder.list_tools、finder.call_tool等即为对应方法的 Span 名{ name: finder.list_tools, context: {trace_id: ..., span_id: ...}, parent_id: ..., attributes: {}, ... }若同时启用file导出器相同的数据会以 JSONL 形式落盘供后续离线分析。进阶把追踪导出到 Jaeger Collector示例 README 给出了将追踪数据接入 Jaeger 的方法先在本地安装 Jaeger官方快速开始指南再在mcp_agent.config.yaml的otel.exporters中追加一个带 Collector 端点的类型化 OTLP 导出器otel: enabled: true exporters: - console - file - otlp: endpoint: http://localhost:4318/v1/traces启用后所有 Span 会经 OTLP/HTTP 协议批量发送到 Jaeger 的 Collector 端点随后可在 Jaeger UI 中按service.name BasicTracingAgentExample检索完整的调用链——包括finder.list_tools、finder.call_tool(fetch_fetch)、llm.generate_str等各个阶段的耗时与父子关系。这一配置在源码中的落地路径为 src/mcp_agent/tracing/tracer.py 的TracingConfig.configure方法资源标识为服务创建Resource写入service.name、service.instance.id、service.version、session.id等属性其中session.id缺省时自动生成 UUID保证每次运行链路可区分采样控制仅当显式设置了sample_rate时才用ParentBased(TraceIdRatioBased(sample_rate))采样器否则全量采样导出器装配遍历exporters解析字符串形式与键值映射形式分别挂载ConsoleSpanExporter、OTLPSpanExporter从 payload 中读取endpoint与headers和FileSpanExporter从 payload 或历史遗留字段中读取path/path_settings自动埋点首次配置时对AnthropicInstrumentor与OpenAIInstrumentor执行全局instrument()从而让底层 LLM SDK 的调用自动产生 Span——这正是所有 Agent 方法 LLM 调用都能被追踪的底层原因若未安装对应 instrumentation 包会记录错误日志提示安装opentelemetry-instrumentation-anthropic。另外TracingConfig还提供flush(timeout_ms)与shutdown()方法用于强制刷出待导出的 Span 以及优雅关闭后台导出线程。参数进阶与排查要点1.exporters的三种写法源码 config.py 明确兼容多种写法可按需选择otel: enabled: true exporters: # 写法一纯字符串简单直观 - console - file - otlp # 写法二键值映射可为 file/otlp 指定详细参数 - file: path: logs/trace.jsonl - otlp: endpoint: http://localhost:4318/v1/traces headers: {Authorization: Bearer xxx} # 写法三历史兼容的 type 字段形式 - type: file path: /tmp/out其中otlp导出器支持endpoint与可选headers对应源码中的 OTLPExporterSettingsfile导出器支持path与path_settings对应 FileExporterSettings。2. 采样率与生产环境建议高吞吐场景下可降低sample_rate以控制数据量例如otel: enabled: true sample_rate: 0.1 # 采样 10% 的链路 exporters: [console, file]3. 排查要点未看到 Span首先确认otel.enabled: true其次确认exporters至少包含console最后确认 logger 的level足够低示例中为debug避免输出被过滤。OTLP 无数据确认 Collector 端点可达http://localhost:4318/v1/traces是 Jaeger 默认的 OTLP/HTTP 接收路径并留意源码 tracer.py 中的错误分支——未提供 endpoint 时仅记录错误日志。密钥缺失示例运行会连接 OpenAI/Anthropic请务必先按 mcp_agent.secrets.yaml.example 创建 secrets 文件否则相关 LLM 调用会失败。延伸阅读追踪体系在仓库中还有其他场景的示例可对照学习examples/tracing/llm直接使用 LLMOpenAI / Anthropic / Azure时的追踪演示generate、generate_str、generate_structured三类生成方式examples/tracing/mcpMCP 服务器层的追踪examples/tracing/temporal与 Temporal 工作流引擎结合时的追踪examples/tracing/langfuse对接 Langfuse 追踪后端的示例追踪配置的完整 schema 可参考 schema/mcp-agent.config.schema.json日志与事件体系的更多细节见 docs/mcp-agent-sdk/advanced/observability.mdx 与 docs/advanced/monitoring.mdx。从控制台到文件、再到 Jaeger 的全链路导出examples/tracing/agent用不到百行代码覆盖了 mcp-agent 追踪体系的核心用法——先跑通示例观察控制台 Span再按需叠加file落盘与otlp接入 Collector即可完成从本地调试到生产可观测的平滑升级。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考