管理可观测性设置

本文档介绍了如何使用 Google Cloud 控制台或 REST API 为 Gemini Enterprise 应用或单个代理配置可观测性设置。

启用逻辑取决于代理类型：

• 核心 Google 助理代理：使用配置中的应用级（引擎级）切换开关。
• 其他智能体（目前仅限 Workflow Builder 中由员工创建的智能体和 Deep Research 智能体）：使用各个智能体设置中的智能体级切换开关。

启用这些设置后，您可以在 Gemini Enterprise Web 应用中查看与助理或智能体互动时产生的以下数据：

• 在 Metrics Explorer 中查看指标。
• 在 Trace 探索器中查看跟踪记录和 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 Admin 角色。

• 现有的 Gemini Enterprise Web 应用。如需了解如何创建新应用，请参阅创建应用。

开启可观测性设置

如需为 Gemini Enterprise 应用或单个代理启用可观测性，您可以使用 Google Cloud 控制台或 REST API。

控制台

如需使用 Google Cloud 控制台开启可观测性设置，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

   Gemini Enterprise

2. 点击要配置的应用的名称。

3. 根据您要配置的代理类型，执行以下操作之一：

   • 核心助理代理：点击配置，然后点击可观测性标签页。
   • 其他智能体（Workflow Builder 员工创建的智能体和 Deep Research 智能体）：点击智能体，点击要配置的智能体的名称，然后点击配置标签页。

4. 您可以开启或关闭以下设置：

   可观测性设置	说明
   启用 OpenTelemetry 跟踪记录和日志的插桩	启用后，您可以在 Cloud Logging 中查看与日志关联的跟踪记录、span、span 日志和指标。
   启用提示输入和回答输出的日志记录	启用后，Cloud Logging 会记录用户提示和回答的完整内容。这包括敏感数据或个人身份信息 (PII)。如需启用此设置，您必须先启用启用 OpenTelemetry 跟踪记录和日志的插桩。 注意：启用此设置会记录可能敏感的数据，包括个人身份信息。 仅限获得授权的人员访问日志。

REST

如需使用 REST API 配置可观测性设置，请参阅以下部分：

• 为 Core Assistant 配置可观测性设置（应用级）
• 为单个代理配置可观测性设置

为 Core Assistant 配置可观测性设置（应用级）

如需在应用级别（适用于 Core Assistant 智能体）使用 REST API 配置可观测性设置，请参阅以下部分：

• 在创建应用时开启可观测性
• 为现有应用开启可观测性

在创建应用时启用可观测性

如需创建启用了可观测性的新应用，请运行以下命令：

关键术语：在 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 为单个智能体（例如 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. 根据您要配置的代理类型，执行以下操作之一：

   • 核心助理代理：点击配置，然后点击可观测性标签页。
   • 其他代理（包括 Workflow Builder 员工创建的代理和 Deep Research 代理）：点击代理，点击要配置的代理的名称，然后点击配置标签页。

4. 您可以关闭以下设置：

   可观测性设置	说明
   启用 OpenTelemetry 跟踪记录和日志的插桩	关闭此设置后，系统会停止收集跟踪记录、span、span 日志和指标。它还会关闭启用提示输入和回答输出的日志记录设置，这意味着不会向 Cloud Logging 发送任何日志。
   启用提示输入和回答输出的日志记录	停用后，Cloud Logging 不会记录提示输入和回答输出。

REST

如需使用 REST API 关闭可观测性设置，请参阅以下部分：

• 在应用层级关闭可观测性（核心助理）
• 为单个代理关闭可观测性

在应用层级关闭可观测性（核心助理智能体）

如需在应用级层关闭可观测性，请运行以下命令：

关键术语：在 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。

为单个代理关闭可观测性

如需为单个智能体（例如 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

后续步骤

• 如需详细了解如何访问 Gemini Enterprise 日志，请参阅访问使用情况审核日志。
• 如需详细了解如何访问 Gemini Enterprise 跟踪记录和 span 数据，请参阅在 Trace 探索器中访问跟踪记录和 span。
• 如需详细了解如何访问 Gemini Enterprise 指标，请参阅在 Metrics Explorer 中访问指标。