管理可觀測性設定

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

啟用邏輯取決於代理程式類型：

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

啟用這項設定後，您可以在 Gemini Enterprise 網頁應用程式中查看下列資料：

• 在 Metrics Explorer 中查看指標。
• 在 Trace Explorer 中查看追蹤記錄和時距。

基本概念

本節將介紹 Gemini Enterprise 可觀測性的重要概念。

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

事前準備

請確認你已具備以下條件：

• Gemini Enterprise 管理員角色。

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

開啟觀測能力設定

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

控制台

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

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

   Gemini Enterprise

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

3. 根據您要設定的代理程式類型，執行下列其中一項操作：

   • 核心 Google 助理代理程式：依序點選「設定」和「可觀測性」分頁標籤。
   • 其他代理程式 (Agent Designer 員工製作的代理程式和 Deep Research 代理程式)：依序點選「代理程式」、要設定的代理程式名稱，然後點選「設定」分頁標籤。

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

   觀測設定	說明
   啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能	啟用後，您可以在 Cloud Logging 中查看與記錄相關聯的追蹤記錄、時距、時距記錄和指標。
   啟用提示詞輸入內容和回覆輸出內容的記錄功能	啟用後，Cloud Logging 會記錄使用者提示詞和回覆的完整內容。包括機密資料或個人識別資訊 (PII)。如要啟用這項設定，請先啟用「啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能」。 注意：啟用這項設定會記錄可能包含 PII 的敏感資料。 僅限授權人員存取記錄。

REST

如要使用 REST API 設定可觀測性，請參閱下列各節：

• 設定 Core Assistant 的可觀測性設定 (應用程式層級)
• 為個別代理程式設定可觀測性

設定 Core Assistant 的可觀測性設定 (應用程式層級)

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

• 建立應用程式時開啟觀測功能
• 為現有應用程式啟用觀測功能

建立應用程式時開啟可觀測性

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

重要用語：在 Gemini Enterprise 中，API 脈絡的「應用程式」一詞可與「引擎」互換使用。Gemini Enterprise 引擎是通用搜尋引擎，其中 app_type 欄位設為 APP_TYPE_INTRANET。

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：要建立的應用程式顯示名稱。

為現有應用程式啟用可觀測性

如要在現有應用程式上啟用可觀測性，請執行下列指令：

重要用語：在 Gemini Enterprise 中，API 脈絡的「應用程式」一詞可與「引擎」互換使用。Gemini Enterprise 引擎是通用搜尋引擎，其中 app_type 欄位設為 APP_TYPE_INTRANET。

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 為個別代理程式 (例如 Agent Designer 代理程式或 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. 根據您要設定的代理程式類型，執行下列其中一項操作：

   • 核心 Google 助理代理程式：依序點選「設定」和「可觀測性」分頁標籤。
   • 其他代理程式 (包括 Agent Designer 員工製作的代理程式和 Deep Research 代理程式)：按一下「代理程式」，然後按一下要設定的代理程式名稱，再按一下「設定」分頁標籤。

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

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

REST

如要使用 REST API 關閉可觀測性設定，請參閱下列章節：

• 在應用程式層級關閉可觀測性 (核心助理)
• 關閉個別代理程式的可觀測性

在應用程式層級關閉可觀測性 (Core Assistant)

如要在應用程式層級關閉可觀測性，請執行下列指令：

重要用語：在 Gemini Enterprise 中，API 脈絡的「應用程式」一詞可與「引擎」互換使用。Gemini Enterprise 引擎是通用搜尋引擎，其中 app_type 欄位設為 APP_TYPE_INTRANET。

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。

為個別代理程式關閉可觀測性

如要為個別代理程式 (例如 Agent Designer 代理程式或 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

後續步驟

• 如要進一步瞭解如何存取 Gemini Enterprise 記錄，請參閱「存取用量稽核記錄」。
• 如要進一步瞭解如何存取 Gemini Enterprise 追蹤記錄和時距資料，請參閱「在 Trace Explorer 中存取追蹤記錄和時距」。
• 如要進一步瞭解如何存取 Gemini Enterprise 指標，請參閱「在 Metrics Explorer 中存取指標」。