使用 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。

支持跟踪的 MCP 服务器

本部分列出了支持跟踪的远程 Google 和 Google Cloud MCP 服务器。本文还介绍了自托管 MCP 服务器如何生成轨迹跨度。

自托管式服务器

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

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

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

如何配置应用

您可以使用任何通过 _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：