使用 Trace 调查 MCP 调用

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

span 记录的是属于较大端到端操作的单个函数或操作。 跟踪记录表示单个端到端操作，由 span 组成。 因此，跟踪记录提供有关所调用函数序列和总体延迟的信息，而 span 提供特定函数的状态和延迟信息。

关于工具

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

模型上下文协议 (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。

支持跟踪记录的 MCP 服务器

本部分列出了支持 跟踪记录的远程 Google 和 Google Cloud MCP 服务器。此外，还介绍了自托管 MCP 服务器如何生成跟踪记录 span。

自托管服务器

我们建议您对自托管 MCP 服务器进行插桩，以将遥测数据发送到您的 Google Cloud 项目。 如果您使用 Python，则插桩可以为 tools/call 操作生成 span。如需了解详情，请参阅 使用 OpenTelemetry 对自托管 MCP 服务器进行插桩。

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

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

如何配置应用

您可以使用任何通过 _meta字段传递跟踪记录上下文的框架或 SDK。这些框架和 SDK 包括 支持 OpenTelemetry 语义惯例（适用于 MCP）的框架和 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：