管理可觀測性設定

本文說明如何使用 Google Cloud 控制台或 REST API，為 Gemini Enterprise 應用程式或個別代理設定觀測能力。

啟用邏輯會因代理類型而異：

  • 核心助理代理：使用設定中的應用程式層級 (引擎層級) 切換鈕。
  • 其他代理：(目前僅限 Workflow Builder 員工製作的代理和 Deep Research 代理)：在個別代理的設定中，使用代理層級切換鈕。

啟用設定後，您可以在 Gemini Enterprise 網頁應用程式中，查看與助理或代理互動的下列資料：

  • 在 Metrics Explorer 查看指標。
  • 在 Trace Explorer 查看追蹤記錄和 Span。

基本概念

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

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

舉例來說，追蹤記錄代表要求的整個生命週期。包括使用者向 Gemini Enterprise 助理提問、Gemini Enterprise 助理回覆，以及回覆觸發的任何後續動作，例如傳送電子郵件。
Span 「Span」是追蹤記錄中單一、有時間限制的工作單位。代表特定作業，例如函式呼叫、API 要求或資料庫查詢。每個 Span 都包含開始和結束時間、專屬 ID，以及與其他 Span 的關係等詳細資料。這些關係共同構成一個追蹤記錄。
Span 記錄 Span 記錄是與特定 Span 相關聯、附有時間戳記的任意形式訊息或事件。這些記錄會提供與 Span 執行作業相關的詳細情境資訊，協助使用者偵錯及瞭解要求流程。
指標 指標是系統在一段時間內收集的數值測量結果。這些指標代表系統的效能、資源使用率或行為。工程師會使用指標監控系統健康狀態、找出趨勢及觸發快訊。
使用情況稽核記錄 使用情況稽核記錄會記錄 Google Cloud 資源中的管理和存取活動。詳細說明執行動作的人員、動作內容、時間和來源。這些記錄對於安全性稽核、法規遵循，以及瞭解資源使用情形至關重要。
Gemini Enterprise 連接器錯誤記錄 Gemini Enterprise 連接器錯誤記錄會擷取將 Gemini Enterprise 與第三方資料來源 (例如 Jira 和 Microsoft OneDrive) 整合時發生的錯誤和失敗。這些記錄包括連線問題、資料轉換問題和 API 錯誤。

事前準備

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

開啟觀測功能設定

如要為 Gemini Enterprise 應用程式或個別代理啟用觀測能力，可以使用 Google Cloud 控制台或 REST API。

控制台

如要使用 Google Cloud 控制台開啟觀測能力設定，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

    Gemini Enterprise

  2. 按一下要設定的應用程式名稱。

  3. 視您設定的代理類型而定，請執行下列其中一項操作：

    • Core Assistant 代理：依序點選「設定」和「觀測能力」分頁標籤。
    • 其他代理 (Workflow Builder 員工建立的代理和 Deep Research 代理)：依序點選「代理」和要設定的代理名稱，然後點選「設定」分頁標籤。

  4. 您可以開啟或關閉下列設定：

    觀測能力設定 說明
    啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能 啟用後，您可以在 Cloud Logging 中查看與記錄相關聯的追蹤記錄、span、span 記錄和指標。
    啟用提示詞輸入內容和回覆輸出內容的記錄功能 啟用後，Cloud Logging 會記錄使用者提示詞和回覆的完整內容。包括機密資料或個人識別資訊 (PII)。如要啟用這項設定，請先啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能。

REST

如要使用 REST API 調整觀測能力設定，請參閱下列各節：

設定 Core Assistant 的觀測能力設定 (應用程式層級)

如要使用 REST API 在應用程式層級 (適用於 Core Assistant 代理) 設定觀測能力，請參閱下列各節：

建立應用程式時啟用觀測能力

如要建立已啟用觀測能力的新應用程式，請執行下列指令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines?engineId=APP_ID" \
-d '{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID",
  "displayName": "APP_DISPLAY_NAME",
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_ENTERPRISE",
    "searchAddOns": ["SEARCH_ADD_ON_LLM"],
    "requiredSubscriptionTier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT"
  },
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "observabilityConfig": {
    "observabilityEnabled": true,
    "sensitiveLoggingEnabled": true
  }
}'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案 ID。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • APP_ID：要建立的應用程式 ID。
  • APP_DISPLAY_NAME：要建立的應用程式顯示名稱。

為現有應用程式啟用觀測能力

如要為現有應用程式啟用觀測能力，請執行下列指令：

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID?updateMask=observabilityConfig" \
-d '{
  "observabilityConfig": {
    "observabilityEnabled": true,
    "sensitiveLoggingEnabled": true
  }
}'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案 ID。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • APP_ID：應用程式 ID。

設定個別代理的可觀測性設定

如要使用 REST API 開啟個別代理 (例如 Workflow Builder 代理或 Deep Research 代理) 的觀測能力，請執行下列指令來更新代理的 observabilityConfig：

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID?updateMask=observabilityConfig" \
-d '{
  "observabilityConfig": {
    "observabilityEnabled": true,
    "sensitiveLoggingEnabled": true
  }
}'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案 ID。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • APP_ID：應用程式 ID。
  • AGENT_ID：要設定的代理 ID

關閉觀測功能設定

如要關閉 Gemini Enterprise 應用程式或個別代理的觀測能力設定，請使用 Google Cloud 控制台或 REST API。

控制台

如要使用 Google Cloud 控制台關閉觀測能力設定，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

    Gemini Enterprise

  2. 按一下要關閉觀測能力設定的應用程式名稱。

  3. 視您設定的代理類型而定，請執行下列其中一項操作：

    • Core Assistant 代理：依序點選「設定」和「觀測能力」分頁標籤。
    • 其他代理 (包括 Workflow Builder 員工建立的代理和 Deep Research 代理)：按一下「代理」，點選要設定的代理名稱，然後按一下「設定」分頁標籤。

  4. 您可以關閉下列設定：

    觀測能力設定 說明
    啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能 關閉這項設定後，系統會停止收集追蹤記錄、Span、Span 記錄和指標。此外，這項設定也會關閉「啟用提示詞輸入內容和回覆輸出內容的記錄功能」設定，也就是說，系統不會將任何記錄傳送至 Cloud Logging。
    啟用提示詞輸入內容和回覆輸出內容的記錄功能 關閉後，Cloud Logging 不會記錄提示詞輸入內容和回覆輸出內容。

REST

如要使用 REST API 關閉觀測能力設定，請參閱下列各節：

在應用程式層級關閉觀測功能 (Core Assistant)

如要在應用程式層級停用觀測能力，請執行下列指令：

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID?updateMask=observabilityConfig" \
-d '{
  "observabilityConfig": {
    "observabilityEnabled": false,
    "sensitiveLoggingEnabled": false
  }
}'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案 ID。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • APP_ID：應用程式 ID。

停用個別代理的觀測能力

如要關閉個別代理 (例如 Workflow Builder 建構代理或 Deep Research 代理) 的觀測能力，請執行下列指令：

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID?updateMask=observabilityConfig" \
-d '{
  "observabilityConfig": {
    "observabilityEnabled": false,
    "sensitiveLoggingEnabled": false
  }
}'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案 ID。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • APP_ID：應用程式 ID。
  • AGENT_ID：要設定的代理 ID

後續步驟