使用 Trace 调查 MCP 调用

您可以配置调用远程 Google Cloud MCP 服务器的智能体应用，以使这些服务器能够生成记录调用状态的 span。 然后，您可以使用 Cloud Trace（用于存储和分析记录工具调用、方法调用以及提示和回答的 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：

产品 参考文档
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 参考文档
Google Security Operations Google SecOps MCP 参考文档
AlloyDB for PostgreSQL AlloyDB for PostgreSQL MCP 参考文档
Agent Search Agent Search MCP 参考文档
Cloud SQL
BigQuery BigQuery MCP 参考文档
Personalized Service Health Personalized Service Health MCP 参考文档
Cloud Billing Cloud Billing MCP 参考文档
Policy Troubleshooter 政策问题排查工具 MCP 参考文档
Managed Service for Apache Airflow Managed Service for Apache Airflow 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。此命名 惯例由 MCP 的 OpenTelemetry 语义惯例定义。

如需查找这些 span，请使用过滤栏并为 mcp.method.name 添加属性过滤条件。将过滤条件的值设置为 tools/call。如需详细 了解这些步骤，请参阅 查看对远程 MCP 服务器的调用。

插桩示例

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

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