使用 Trace 调查 MCP 调用

Cloud Trace 会收集并显示工具调用、方法调用、提示和回答等数据，以帮助您了解代理应用的运行情况。本文档介绍了如何配置调用远程 Google Cloud MCP 服务器的智能体应用，以使这些服务器能够生成记录调用状态的 span。

span 记录的是单个函数或操作，它是较大端到端操作的一部分。轨迹表示单个端到端操作，由 span 组成。因此，轨迹可提供有关所调用函数序列和总体延迟时间的信息，而 span 可提供特定函数的状态和延迟时间信息。

工具简介

借助工具，智能体可以收集训练数据之外的信息，通常是通过与外部 API 互动来实现。借助 Google Cloud MCP 服务器，智能体应用可以调用可调用 Google Cloud API 方法的工具。例如，您的应用可以调用 list_log_entries 工具来提取最近的日志数据。

Model Context Protocol (MCP) 是一种规范，用于定义 AI 智能体与外部工具、数据源和资源进行通信和交互的标准化方式。如需查看提供 MCP 服务器的产品的完整列表以及指向其参考文档的链接，请参阅支持的产品。

如何将跟踪上下文传递给 MCP 服务器

MCP 参考页面（例如 list_log_entries 的文档）提供了一个示例 curl 命令，您可以使用该命令向工具发送 HTTP 请求。请求中发送的 JSON 载荷类似于以下内容：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

name 字段的值列出了工具名称，例如 list_log_entries。 arguments 字段包含操作完成请求所需的信息。

MCP 标准定义了一个 _meta 字段，允许客户端和服务器将元数据附加到其互动中。客户端和服务器可以使用此字段传递跟踪上下文：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
    "_meta": {
        "traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG"
        "tracestate": "Vendor specific information."
      }
  },
  "id": 1
}

_meta 数据包含 traceparent 字段。此字段的值的格式由万维网联盟 (W3C) traceparent 标头定义。此值包括以下内容：

  • traceparent 规范的版本 (00)。
  • 轨迹的 ID (TRACE_ID)。
  • 调用 span 的 ID (PARENT_SPAN_ID)。
  • 指定调用方 span 是否对请求进行了抽样 (SAMPLED_FLAG)。如果进行了抽样，此字段的值为 01；如果未进行抽样，此字段的值为 00。

tracestate 字段包含特定于供应商的跟踪信息。

限制

  • 跟踪记录上下文必须遵循 W3C 跟踪记录上下文标准，并且 sampled 标志必须设置为 1。

  • 远程 Google Cloud MCP 服务器可以为 tools/call 操作生成单个 span，但不会为其他类型的操作生成 span，也不会为 tools/call 操作生成子 span。

  • 远程 Google Cloud MCP 服务器仅在请求通过身份验证、授权和其他内部检查时生成 span。

支持跟踪的远程 Google 和 Google Cloud MCP 服务器

以下产品包含一项集成，可让其远程 MCP 服务器为 tools/call 操作生成跟踪记录 span：

产品 参考文档
Cloud Logging Cloud Logging MCP 参考文档
Cloud Monitoring Cloud Monitoring MCP 参考
Maps Grounding Lite Maps Grounding Lite MCP 参考文档
GKE GKE MCP 参考文档
Cloud Run Cloud Run MCP 参考
Compute Engine Compute Engine MCP 参考

如何配置应用

您可以使用任何通过 _meta 字段传递轨迹上下文的框架或 SDK。这些框架和 SDK 包括支持 MCP 的 OpenTelemetry 语义惯例的框架和 SDK。

例如，您可以使用智能体开发套件 (ADK) 框架。 如需了解详情，请参阅使用 OpenTelemetry 对 ADK 应用进行插桩。

如何查看 span

如需查看跟踪记录数据，请使用 Trace 探索器。在此页面上，您可以查看有关跟踪记录数据的汇总信息，并探索各个跟踪记录和 span。如需了解详情，请参阅查找和探索轨迹。

如需查看由 MCP 服务器写入的 span，请按 span 名称过滤跟踪记录数据。例如，某些远程 Google Cloud MCP 服务器在收到 tools/call 操作时可以生成跟踪记录 span。这些 span 采用以下命名惯例：

tools/call NAME

在上面的表达式中，NAME 指的是调用的端点。例如，这可能类似于 list_keys。此命名惯例由 OpenTelemetry MCP 语义惯例定义。

如需查找这些 span，请使用过滤栏并添加 mcp.method.name 的属性过滤条件。将过滤条件的值设置为 tools/call。

插桩示例

如需了解插桩建议，请参阅选择插桩方法。

我们提供的插桩示例使用 OpenTelemetry：