管理可观测性设置

本文档介绍了如何使用 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 应用或各个智能体开启可观测性，您 可以使用控制台或 REST API。 Google Cloud

控制台

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

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

    Gemini Enterprise

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

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

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

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

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

REST

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

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

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

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

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

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 为单个智能体（例如 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 跟踪记录和日志的插桩 关闭后，此设置会停止收集跟踪记录、span、 span 日志和指标。它还会关闭启用 提示输入和回答输出的日志记录 设置，这意味着不会向 Cloud Logging 发送任何日志。
    启用提示输入和回答输出的日志记录 关闭后，Cloud Logging 不会记录提示输入和 回答输出。

REST

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

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

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

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

后续步骤