为多项目查询配置可观测性范围

本文档介绍了当日志数据存储在多个项目中时，如何创建图表或查看日志数据。默认情况下，可视化工具只能使用项目中的原始数据。不过，如果您配置了范围，可视化和分析工具便可以查询存储在多个项目中的数据。

如果您只想监控或查看存储在一个Google Cloud 项目中的数据，则无需执行任何配置。

范围提供读取时聚合

借助范围，可视化和分析工具可以实时聚合存储在多个位置的数据。作用域不会控制数据的存储位置。相反，查询引擎会依赖范围来确定在何处搜索数据。

指标和轨迹数据始终存储在数据源自的 Google Cloud 项目中。如需在单个图表中查看存储在多个项目中的指标数据，请配置指标范围以列出这些项目。配置此范围后，当您创建图表或提醒政策时，这些服务发出的查询会自动返回所列项目的指标数据。对于轨迹数据，行为类似。

默认情况下，日志数据存储在数据源自的 Google Cloud 项目、结算账号、文件夹或组织中。不过，您可以配置 Logging，将日志数据从其来源资源路由到其他位置，例如其他项目或集中式日志存储桶。在所有情况下，都应配置自定义日志范围。我们建议您的日志范围列出日志视图，而不是项目；日志视图可提供对日志存储桶中部分日志条目的读取权限。例如，如果您有存储在三个项目中的日志数据，则可以将日志视图配置为包含每个项目的 _Default/_AllLogs 视图。

Google Cloud Observability 如何使用范围

Google Cloud Observability 分析和可视化工具依赖于数据类型专属范围来确定要查询哪些资源，以获取工具要显示或分析的数据。

示例：

  • Logs Explorer 页面打开时，系统会查询默认日志范围中列出的资源，以获取日志数据。打开此页面后，您可以使用工具栏选项查询不同范围内的资源。
  • 当 Trace 探索器页面打开时，系统会查询默认跟踪记录范围中列出的项目，以获取跟踪记录数据。打开此页面后，您可以使用工具栏选项查询其他范围内的资源。
  • 创建提醒政策时，Monitoring 会查询指标范围中列出的项目的指标数据。然后，它会分析查询响应，并确定是否创建突发事件。
  • 使用 Metrics Explorer 页面创建图表时，您需要指定要绘制的指标。Monitoring 会查询指标范围内列出的项目的指标数据，然后显示查询结果。

在查询返回数据之前，Logging 和 Trace 会验证您对资源的 Identity and Access Management (IAM) 角色。例如，如果日志范围指定了您未获授权读取日志数据的项目，那么对该项目的查询不会返回数据。

监控会验证您在发出查询的项目中的 IAM 角色。假设名为 AllEnv 的项目的指标范围列出了以下项目：AllEnv、Prod 和 Staging。另假设您已获得 AllEnv 项目的 Monitoring Viewer 角色。使用 AllEnv 项目时，您在 Metrics Explorer 页面上创建的图表会自动显示这三个项目的指标数据。

Google Cloud Observability 范围

本部分介绍了 Google Cloud Observability 使用的范围。

可观测性范围

可观测性范围指定了默认日志范围和默认跟踪记录范围。日志浏览器和 Trace 探索器等页面会在打开时使用默认范围来确定要查询哪些资源。例如，假设您有一个应用，可在三个项目中生成跟踪数据。您可以配置轨迹探索器页面，通过设置默认轨迹范围来自动查询这三个项目。

如果您未配置可观测性范围，则会发生以下情况：

  • 日志浏览器页面会查询项目中的日志数据。
  • Trace 探索器页面会查询项目中的跟踪记录数据。

可观测性范围不适用于指标数据。

何时配置可观测性范围

在以下情况下配置可观测性范围：

  • 您创建了一个自定义日志范围，并希望默认情况下查询该范围中列出的资源。

  • 您创建了一个自定义跟踪范围，并希望默认查询该范围中列出的项目。

与可观测性范围相关的限制

说明 最大值
每个项目的可观测性范围数量 1

日志范围

Logs Explorer 页面和显示日志数据的信息中心会使用日志范围：

  • 日志浏览器页面打开时，系统会自动查询默认日志范围中列出的资源，以获取日志数据。此页面还提供了一些控件，可让您在不同范围之间切换。

  • 对于信息中心，实现方式决定了系统是查询项目还是查询默认日志范围中列出的资源。

日志范围可以列出日志视图、项目、文件夹和组织。

如果您未配置自定义日志范围，日志浏览器页面会查询您项目中的日志数据。

何时创建自定义日志范围

为以下配置创建自定义日志范围：

在所有情况下，请配置自定义日志范围以列出一个或多个日志视图。这些日志视图可能位于集中式日志存储桶中，也可能位于不同的日志存储桶中。如果您使用集中式日志存储桶，则可以创建多个自定义日志范围，每个范围都有一组自己的日志视图。

如果您创建了自定义日志范围，请考虑更新默认日志范围。

配置日志范围时的最佳实践

  • 仅包含日志视图。
  • 请勿配置同时列出项目和日志视图的范围。

与日志范围相关的限制

说明 最大值
每个项目的日志范围数量 100
每个日志范围的项目数量 5
每个日志范围的日志视图或项目数量 100

如需了解详情，请参阅创建和管理日志范围。

指标范围

指标范围供 Cloud Monitoring 发出的所有查询使用。例如，提醒政策和图表工具（如 Metrics Explorer）会向指标范围中列出的项目发出查询。

如果您未配置指标范围，Monitoring 服务会查询您的项目以获取指标数据。

何时配置指标范围

在以下任一情况下，请配置指标范围：

  • 您希望将存储在不同项目中的数据绘制成图表。
  • 您希望使用提醒政策来监控存储在不同项目中的数据。
  • 您可以通过 App Hub 注册应用。如需了解此类情况，请参阅管理项目的指标范围。

与指标范围相关的限制

说明 最大值
每个项目的指标范围数量 1
每个指标范围的项目数量 375

如需了解详情，请参阅指标范围概览。

跟踪范围

Trace 探索器页面会使用跟踪记录范围。当此页面打开时，系统会自动查询默认跟踪记录范围中所列项目的跟踪记录数据。此页面还提供了一些控件，可让您在不同范围之间切换。

如果您未配置自定义跟踪记录范围，Trace 探索器页面会查询项目中的跟踪记录数据。

何时创建自定义跟踪范围

当您的应用依赖于不同 Google Cloud 项目中的资源时，请创建自定义跟踪记录范围。

与轨迹范围相关的限制

说明 最大值
每个项目的跟踪记录范围数量 100
每个跟踪记录范围的项目数量 20

如需了解详情，请参阅创建和管理跟踪记录范围。

配置可观测性范围

本部分不适用于文件夹或组织。

对于日志和跟踪记录数据，您在所查看项目中的 Identity and Access Management (IAM) 角色以及任何搜索的项目和日志视图会影响查询返回的数据。如果您发出查询来查看您无权查看的日志数据，则该查询不会返回任何日志数据。

对于指标数据，当配置项目的指标范围后，该项目会被授予对其指标范围内列出的项目所存储的指标数据的读取权限。当用户获得 Identity and Access Management 角色，从而可以在项目中查看指标数据时，他们可以查看该项目可用的指标数据。

如需配置可观测性范围，您需要设置默认日志范围和默认跟踪记录范围。本部分的其余内容将介绍如何完成这些操作。

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. 如需获得创建和查看范围所需的权限，请让您的管理员为您授予以下 IAM 角色：

    • 如需创建和查看日志范围以及获取默认日志范围：针对您的项目的 Logs Configuration Writer (roles/logging.configWriter)
    • 如需修改指标范围：针对您的项目以及要添加到指标范围的每个项目的 Monitoring Admin (roles/monitoring.admin)
    • 如需创建和查看跟踪记录范围，以及获取和设置默认范围：针对您的项目的 Observability Scopes Editor (roles/observability.scopesEditor)

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

    可观测性范围编辑者角色包含专用权限，可让您创建和查看轨迹范围。这些权限无法包含在自定义 IAM 角色中。

  9. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

      安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init

      如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

    查看和设置默认范围

    控制台

    如需配置可观测性范围，您需要配置其组件，即默认日志范围、指标范围和默认跟踪记录范围：

    1. 在 Google Cloud 控制台中，前往 设置页面：

      前往设置

      如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

    2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。

    3. 配置默认日志范围：

      1. 选择日志范围标签页。

        列出了现有的日志范围。带有“默认”图标 的条目是默认日志范围。如果您要创建日志范围，请点击创建日志范围，然后完成对话框。如需了解详情，请参阅创建和管理日志范围。

      2. 找到要指定为默认的条目，点击 更多，然后选择设为默认。

    4. 配置指标范围：

      1. 选择“指标范围”标签页。
      2. 在 Google Cloud 项目窗格中，点击添加项目，然后完成对话框。如需了解详情，请参阅配置指标范围。

    5. 配置默认跟踪记录范围：

      1. 选择跟踪记录范围标签页，然后执行以下操作：

        列出了现有的跟踪记录范围。带有“默认”图标 的条目是默认跟踪记录范围。如果您要创建跟踪记录范围，请点击创建日志范围，然后完成对话框。如需了解详情，请参阅创建和管理跟踪记录范围。

      2. 找到要指定为默认的条目，点击 更多，然后选择设为默认。

    gcloud

    如需查看和设置可观测性范围，请执行以下操作：

    1. 如需查看可观测性范围的设置，请运行 gcloud observability scopes describe 命令。

      在使用下面的命令数据之前，请先进行以下替换：

      • OBSERVABILITY_SCOPE_ID：Scope 对象的名称。此值必须设置为 _Default。
      • LOCATION：位置字段必须设置为 global。
      • PROJECT_ID：项目的标识符。

      执行 gcloud observability scopes describe 命令：

      Linux、macOS 或 Cloud Shell

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID \
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID `
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID ^
   --location=LOCATION^
   --project=PROJECT_ID

      对该命令的响应如下所示： 

      logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default
traceScope: projects/my-project/locations/global/traceScopes/_Default
name: projects/my-project/locations/global/scopes/_Default

    2. 如需更新可观测性范围，请运行 gcloud observability scopes update 命令。在 update 命令中，您可以添加 --log-scope 标志来更新默认日志范围。

      在使用下面的命令数据之前，请先进行以下替换：

      • OBSERVABILITY_SCOPE_ID：Scope 对象的名称。此值必须设置为 _Default。
      • LOG_SCOPE_FQN_ID：日志范围的完全限定 ID。此字段采用以下格式： 
        logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/logScopes/LOG_SCOPE_ID

        在上面的表达式中，LOG_SCOPE_ID 是日志范围的 ID。例如，my-scope。

      • LOCATION：位置字段必须设置为 global。
      • PROJECT_ID：项目的标识符。

      执行 gcloud observability scopes update 命令：

      Linux、macOS 或 Cloud Shell

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID \
   --log-scope=LOG_SCOPE_FQN_ID\
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID `
   --log-scope=LOG_SCOPE_FQN_ID`
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID ^
   --log-scope=LOG_SCOPE_FQN_ID^
   --location=LOCATION^
   --project=PROJECT_ID

      例如，如果 LOG_SCOPE_ID 的值为 my-scope，则响应如下所示： 

      Updated scope [_Default].
logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-scope
name: projects/my-project/locations/global/scopes/_Default

    REST

    如需使用 API 调用获取和设置默认日志范围或默认跟踪记录范围，请配置可观测性范围。可观测性范围会列出默认日志范围和默认跟踪记录范围：

    • 如需获取项目的默认可观测性范围，请向 projects.locations.scopes.get 端点发送请求。您必须指定路径参数。响应是一个 Scope 对象，其中列出了默认日志范围和默认跟踪记录范围。

    • 如需更新项目的默认可观测性范围，请向 projects.locations.scopes.patch 端点发送请求。您必须指定路径参数、查询参数并提供 Scope 对象。查询参数用于标识更改的字段。响应是一个 Scope 对象。

    这两个端点的路径参数采用以下格式：

    projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

    上面表达式中的字段含义如下：

    • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
    • LOCATION：位置字段必须设置为 global。
    • OBSERVABILITY_SCOPE_ID：Scope 对象的名称。此字段必须设置为 _Default。名称为 _Default 的 Scope 对象会自动创建，用于存储有关默认日志范围和默认跟踪记录范围的信息。

    如需向 API 端点发送命令，您可以使用 APIs Explorer，以便从参考页面发出命令。例如，如需获取当前默认范围，您可以执行以下操作：

    1. 点击 projects.locations.scopes.get。

    2. 在尝试此方法微件的名称字段中输入以下内容：

      projects/PROJECT_ID/locations/global/scopes/_Default

      在复制上述字段之前，请将 PROJECT_ID 替换为您的项目名称。

    3. 选择执行。

    4. 在授权对话框中，完成所需的步骤。

      响应类似于以下示例：

      {
"name": "projects/my-project/locations/global/scopes/_Default",
"logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
"traceScope": "projects/my-project/locations/global/traceScopes/_Default"
}

    详细了解范围

    如需详细了解范围，请参阅以下文档：