存取追蹤記錄和時距

本文說明如何存取及查看 Gemini Enterprise 應用程式產生的追蹤記錄和 Span。追蹤記錄和 Span 可讓您深入瞭解應用程式中要求的效能和執行流程，例如使用助理或代理時。

您可以使用 Trace Explorer 查看追蹤記錄資料，也可以直接在個別代理中使用代理的「追蹤記錄」分頁。

基本概念

本節介紹 Gemini Enterprise 觀測能力相關的重要概念。

概念 說明
Trace 追蹤記錄是一組 span，代表單一要求或交易在不同服務和元件中的流程。

舉例來說，追蹤記錄代表要求的整個生命週期。包括使用者向 Gemini Enterprise 助理提問、Gemini Enterprise 助理回覆，以及回覆觸發的任何後續動作，例如傳送電子郵件。
Span 「Span」是追蹤記錄中單一、有時間限制的工作單位。代表特定作業，例如函式呼叫、API 要求或資料庫查詢。每個 Span 都包含開始和結束時間、專屬 ID，以及與其他 Span 的關係等詳細資料。這些關係共同構成一個追蹤記錄。
Span 記錄 Span 記錄是與特定 Span 相關聯、附有時間戳記的任意形式訊息或事件。這些記錄會提供與 Span 執行作業相關的詳細情境資訊，協助使用者偵錯及瞭解要求流程。

事前準備

請確認下列各項均已達成或備妥：

  • Gemini Enterprise 管理員角色或 Google Cloud 控制台 Gemini Enterprise 企業版使用者角色。

  • 現有的 Gemini Enterprise 網頁應用程式。如要瞭解如何建立新應用程式，請參閱「建立應用程式」。

  • 如要存取追蹤記錄，您必須具備 Cloud Trace 使用者角色 (roles/cloudtrace.user)。

  • 啟用觀測能力設定「Enable instrumentation of OpenTelemetry traces and logs」(啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能)。啟用方式取決於代理類型：Core Assistant 代理是在應用程式層級設定中啟用，而 Workflow Builder 員工自製代理和 Deep Research 代理則是在代理的「設定」分頁中啟用。詳情請參閱「管理觀測能力設定」。

資料保留

Gemini Enterprise 應用程式產生的追蹤記錄和 span 會儲存在 Google Cloud 專案的 Cloud Trace 中，並由 Cloud Trace 管理保留期限。根據預設，Cloud Trace 會將 Span 資料保留 30 天，超過保留期限的資料會自動刪除。如要查看權威且最新的保留值，請參閱「Cloud Trace 配額和限制」說明文件中的「Cloud Trace 保留期限」。

在 Trace Explorer 中存取追蹤記錄

如要使用 Trace Explorer 存取追蹤記錄和 span，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Trace Explorer」頁面。

    前往 Trace Explorer

  2. 選取建立 Gemini Enterprise 應用程式的 Google Cloud 專案。您會看到專案的所有 span。

  3. 在表格中，按一下「Span ID」(Span ID) 即可查看追蹤記錄詳細資料，包括 Span 的時間長度和其他屬性。

    Google Cloud 控制台中的 Trace Explorer 螢幕截圖，顯示 Span 清單，其中包含 Span ID、Trace ID、開始時間、時間長度和服務等資料欄。

篩選及搜尋追蹤記錄

在專案的 Trace Explorer 中，您可以使用下列篩選器、查詢參數和屬性，隔離及分析 Gemini Enterprise 代理和資料連接器的執行作業：

  • 多面向篩選器：
    • 服務：依 AssistantService 或 connectorsexecution 篩選，隔離平台代理和資料連接器要求路徑。
    • Span：依 /AssistantService.StreamAssist 篩選，找出根使用者輪流 span，或搜尋子 span，例如 execute_tool <tool_name> 和 invoke_connector <connector>。
  • 直接查詢追蹤記錄 ID：使用標準 32 個字元的 W3C 追蹤記錄 ID 直接尋找追蹤記錄，該 ID 可從 StreamAssist 的 x-cloud-trace-context 回應標頭中擷取。
  • 自訂屬性：依 execute_tool 或 invoke_connector span 的 gemini_enterprise.assist_token 屬性查詢，將回合層級舊版輔助權杖對應至 W3C 追蹤記錄瀑布圖。
  • 資源屬性：每個匯出的 span 都會包含 cloud.region，
  • 資源屬性：每個匯出的 span 都會包含 cloud.region 屬性。這項屬性代表處理要求的 Gemini Enterprise 服務位置，例如 global、us 或 eu。您可以依這項屬性篩選，比較各區域的成效。如果資料連接器在某個位置成功，但在另一個位置失敗，這項比較就很有用。這個值代表提供應用程式的位置，而非託管第三方資料來源的區域。如要套用這項篩選器，請參閱「套用 Span 篩選器」。

存取代理的追蹤記錄

您也可以直接在代理的「追蹤記錄」分頁查看個別代理的追蹤記錄 span，其中會依時間順序詳細摘要 span 追蹤記錄和父項/子項執行結構。

如要存取代理的追蹤記錄，請按照下列步驟操作：

  1. 在 Google Cloud 控制台前往應用程式，然後點選「代理」。
  2. 選取要檢查的代理，然後按一下「Traces」(追蹤記錄) 分頁標籤。

追蹤記錄摘要表

「Traces」(追蹤記錄) 分頁中的主表格會顯示各個追蹤記錄 span 的下列資訊：

  • 狀態：追蹤記錄目前的狀態 (目前顯示「未設定」)。
  • 追蹤記錄 Span ID：追蹤記錄 Span 的專屬 ID。按一下 Span ID 連結，即可深入查看詳細資料。
  • Span Name：簡短說明 Span 執行的工作。Gemini Enterprise 資料連接器的範圍範例如下：
    • execute_tool <tool_name>：在 Agent Runtime 的工具調度層中發出 (例如 execute_tool federated_search)。
    • invoke_connector <connector>：由連接器執行層產生，代表特定連接器 (例如 invoke_connector jira 或 invoke_connector servicenow) 的要求邏輯，會取代預設的服務端 RPC 跨度。
  • Span Type：Span 的類型。選項包括：
    • Agent to Tool：代理叫用外部工具 (重複用於 execute_tool 和 invoke_connector 作業)。
    • Invoke Agent：叫用代理。
    • Agent to Model：代理向大型語言模型提出的要求。
  • 時間長度：完成追蹤記錄 span 所需的時間 (以分鐘為單位)。
  • 輸入：傳送至 Span 的輸入資料或訊息 (如有)。
  • 輸出：Span 傳回的輸出結果 (如有)。
  • 開始時間：Span 開始執行的確切時間戳記。

詳細追蹤記錄檢視畫面

點選「Trace span ID」，即可開啟詳細資料頁面，其中包含：

  1. 摘要：查看基準中繼資料，包括「Start time」(開始時間)、「Duration」(時間長度)和「Spans」(Span) 總數。您可以點選「在 Cloud Trace 中查看」，或切換「圖表」和「時間軸」檢視畫面按鈕。
  2. 圖表：在圖形階層或時間軸檢視畫面之間切換，顯示所有追蹤記錄 span 的上下層關係。
  3. 所選 Span 詳細資料：選取單一 Span 即可顯示詳細區段，其中可能包括：
    • 摘要：顯示 Span 名稱、目標服務、執行這項動作的 Span 總數，以及總時間長度 (以秒為單位)。
    • 記錄：查看相關事件詳細資料 (如有設定)。按一下「查看記錄」，直接前往標準記錄。
    • 評估：顯示所有評估結果 (如有設定)。
    • 輸入和輸出：完整的要求和回應酬載。
    • 記錄檔和事件：執行這個 Span 期間發生的事件清單。
    • 堆疊追蹤：Span 執行失敗時的錯誤詳細資料。
    • 中繼資料和連結：參照相關 Cloud Explorer 實體的連結。
    • 屬性：資源標記和其他鍵/值觀測能力參數。

Google Cloud 控制台「追蹤記錄」分頁的螢幕截圖，顯示 Span 時間軸和 Span 摘要

父項-子項 Span 階層

執行資料連接器時，在單一 W3C 追蹤記錄中建立父項與子項 span 巢狀結構，有助於精確找出延遲或錯誤發生的位置：

  1. /AssistantService.StreamAssist：啟動要求的根 C++ 平台 span。
  2. invoke_agent core_assistant：代理執行時間範圍。
  3. execute_tool <tool_name>：執行中的工具執行作業 span (例如 execute_tool federated_search)。
  4. invoke_connector <connector_name> (例如 invoke_connector jira 或 invoke_connector servicenow)：連接器執行時間範圍，代表對第三方端點的要求生命週期。

實驗性生成式 AI 語意慣例遙測

除了穩定的遙測資料外，Gemini Enterprise 追蹤記錄 span 還包含更豐富的中繼資料，這些資料是以 OpenTelemetry 生成式 AI 語意慣例為基礎。OpenTelemetry 將這些慣例歸類為開發狀態。這個狀態適用於早期階段的規格，這些規格可能會變更或移除，不應在正式環境中使用。由於這些慣例尚未穩定，因此這項 Gemini Enterprise 遙測功能仍處於實驗階段。這些 span 包含 gen_ai.* 屬性，用於描述代理、模型和工具活動，例如代理和工具執行，以及提示和回覆步驟。

只有在觀測能力設定允許記錄提示詞輸入內容和回覆輸出內容時，追蹤記錄 span 中的提示詞和回覆內容 (例如提示詞文字和生成的回覆) 才會顯示。否則，內容會經過遮蓋或省略。如要變更這些設定，請參閱「管理觀測能力設定」。