管理可观测性设置

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

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

• 核心助理代理：在配置中使用应用级（引擎级）切换开关。
• 其他智能体（目前仅限 Agent Designer 员工制作的智能体和 Deep Research 智能体）：使用各个智能体设置中的智能体级切换开关。

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

• 在 Metrics Explorer 中查看指标。
• 在 Trace 探索器中查看轨迹和 span。

主要概念

本部分介绍了与 Gemini Enterprise 中的可观测性相关的关键概念。

概念	说明
轨迹	轨迹是一组 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. 根据您要配置的代理类型，执行以下操作之一：

   • 核心助理代理：点击配置，然后点击可观测性标签页。
   • 其他代理（Agent Designer 员工制作的代理和 Deep Research 代理）：点击代理，点击要配置的代理的名称，然后点击配置标签页。

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

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

REST

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

• 为核心助理配置可观测性设置（应用级）
• 为单个代理配置可观测性设置

为核心助理（应用级）配置可观测性设置

如需在应用级层使用 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 为单个代理（例如 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. 根据您要配置的代理类型，执行以下操作之一：

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

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

   可观测性设置	说明
   启用 OpenTelemetry 跟踪记录和日志的插桩	关闭此设置后，系统会停止收集轨迹、跨度、跨度日志和指标。它还会关闭启用提示输入和回答输出的日志记录设置，这意味着不会向 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。

为单个代理停用可观测性

如需为单个智能体（例如 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 跟踪记录和 span 数据，请参阅在 Trace 探索器中访问跟踪记录和 span。
• 如需详细了解如何访问 Gemini Enterprise 指标，请参阅在 Metrics Explorer 中访问指标。