使用 Trace 檢查 MCP 呼叫

Cloud Trace 會收集並顯示工具呼叫、方法叫用、提示和回覆等資料，協助您瞭解代理程式應用程式的行為。本文說明如何設定會呼叫遠端 Google Cloud MCP 伺服器的代理程式應用程式，讓這些伺服器產生記錄呼叫狀態的時距。

「範圍」會記錄屬於較大型端對端作業的單一函式或作業。「追蹤記錄」代表單一端對端作業，由範圍組成。因此，追蹤記錄會提供所呼叫函式序列和整體延遲時間的相關資訊，而範圍則會提供特定函式的狀態和延遲時間資訊。

關於工具

工具可讓代理從訓練資料以外的來源收集資訊，通常是透過與外部 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)。
  • 呼叫範圍的 ID (PARENT_SPAN_ID)。
  • 指定呼叫範圍是否對要求進行取樣 (SAMPLED_FLAG)。如果取樣，這個欄位的值為 01；如果未取樣，則為 00。

tracestate 欄位會攜帶供應商專屬的追蹤資訊。

限制

  • 追蹤脈絡必須遵循 W3C 追蹤脈絡標準，且 sampled 旗標必須設為 1。

  • 遠端 Google Cloud MCP 伺服器可以為 tools/call 作業產生單一時距，但不會為其他類型的作業或 tools/call 作業的子時距產生時距。

  • 只有在要求經過驗證、授權並通過其他內部檢查時，遠端 Google Cloud MCP 伺服器才會產生範圍。

支援追蹤的遠端 Google 和 MCP 伺服器 Google Cloud

下列產品包含整合功能，可讓遠端 MCP 伺服器為 tools/call 作業產生追蹤記錄範圍：

如何設定應用程式

您可以使用任何架構或 SDK，透過 _meta 欄位傳遞追蹤內容。這些架構和 SDK 包括支援 MCP 適用的 OpenTelemetry 語意慣例的架構和 SDK。

舉例來說，您可以使用 Agent Development Kit (ADK) 架構。詳情請參閱「使用 OpenTelemetry 檢測 ADK 應用程式」。

如何查看範圍

如要查看追蹤記錄資料，請使用 Trace 探索工具。這個頁面可讓您查看追蹤記錄資料的匯總資訊，並探索個別追蹤記錄和範圍。詳情請參閱「尋找及探索追蹤記錄」。

如要查看 MCP 伺服器寫入的時距，請依時距名稱篩選追蹤記錄資料。舉例來說，部分遠端 Google Cloud MCP 伺服器收到 tools/call 作業時，可以產生追蹤範圍。這些範圍的命名慣例如下：

tools/call NAME

在上述運算式中，NAME 是指叫用的端點。例如：list_keys。這個命名慣例由 MCP 的 OpenTelemetry 語意慣例定義。

如要找出這些範圍，請使用篩選列，並新增 mcp.method.name 的屬性篩選條件。將篩選器的值設為 tools/call。

檢測設備範例

如需檢測點建議，請參閱「選擇檢測點方法」。

我們提供的檢測範例使用 OpenTelemetry：

  • 如需使用以收集器為準的匯出作業的範例，請參閱下列內容：

    這些範例會將追蹤資料傳送至 Telemetry API。

  • 如要瞭解如何直接匯出追蹤資料，並將該資料傳送至 Telemetry API，請參閱「從 Trace 匯出工具遷移至 OTLP 端點」。

  • 如需範例，瞭解如何設定具備代理功能的應用程式來收集提示和回覆，請參閱「如何檢測生成式 AI 應用程式」。

  • 如要瞭解哪些遠端 Google Cloud MCP 伺服器支援追蹤記錄產生功能，以及如何設定應用程式，指示這些伺服器建立時距，請參閱「使用 Trace 檢查 MCP 呼叫」。