保存或共享 SQL 查询

您可以在 Observability Analytics 中保存和共享 SQL 查询，以便重新运行频繁的调查，并与项目中的团队成员协作。您可以将已保存的查询设为私密，供自己使用，也可以与其他项目成员共享。如果您之前未在 Observability Analytics 中编写过查询，请先参阅使用 Observability Analytics 查询和分析遥测数据。

准备工作

配置项目、IAM 角色，然后选择您计划使用的界面。

配置项目和角色

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

  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 role (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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 role (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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

  8. 如需获得加载可观测性分析页面、编写、运行和保存私密查询所需的权限，请让管理员为您授予以下 IAM 角色：

    • Observability View Accessor (roles/observability.viewAccessor) 位于您要查询的可观测性视图上。此角色支持 IAM 条件，可让您将授予的权限限制为仅针对特定视图。如果您未为角色授予附加条件，则主账号可以访问所有可观测性视图。
    • 针对项目的 Observability Analytics User (roles/observability.analyticsUser)。此角色包含保存和运行专用查询以及运行共享查询所需的权限。
    • 项目的 Logs Viewer (roles/logging.viewer) 角色。
    • 您要查询的日志视图所存储在的项目中的 Logs View Accessor (roles/logging.viewAccessor)。

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

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

选择您计划使用的界面

控制台

当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

REST

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

    安装 Google Cloud CLI。

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

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

保存查询

您运行的所有查询都会自动保存 30 天，您可以通过选择 Observability Analytics 页面上的最近标签页来访问这些查询。您可以搜索、查看、运行和共享最近标签页中列出的查询。

如需重复使用查询、添加自定义说明或与队友共享查询，请保存查询。您可以按名称、说明和公开范围标签搜索和排序已保存的查询。您还可以修改和删除这些查询。您保存的查询会保留，直到您将其删除。

您可以为每个 Google Cloud 项目保存 10,000 个查询。

控制台

如需保存查询，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Observability Analytics 页面：

    前往 Observability Analytics

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

  2. 使用查询填充查询窗格。

    您可以通过以下方式填充查询窗格：输入新查询、从最近标签页中选择查询或是从已保存标签页中选择查询。

    您的查询可以包含任意有效视图、多个视图和分析视图。

    当查询窗格中的查询有效时， 保存按钮会处于启用状态。

  3. 点击 保存，选择保存查询，然后填写名称和说明字段。您为这些字段设置的值会显示在已保存标签页上。

  4. 可选：如需让所有有权访问 Google Cloud 项目的 Observability Analytics 页面的用户都能查看和运行已保存的查询，请启用与项目共享切换开关。

    默认情况下，此切换开关处于停用状态，仅您可查看相应数据。

  5. 点击保存查询。

  6. 可选：如需查看、排序和运行您可查看的已保存查询，请选择已保存标签页。

    您可以按名称、说明和公开范围标签对已保存的查询进行排序和过滤。您还可以按查询内容进行过滤。

您可以使用已保存标签页上的选项修改和删除自己创建的查询：

  • 如需修改查询，请点击 更多选项，然后选择修改。您可以修改名称和说明字段的值；但无法修改查询本身。

  • 如需删除已保存的查询，请点击 更多选项，然后选择删除。

gcloud

如需创建并保存查询，请执行以下操作：

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

    • DISPLAY_NAME：已保存查询的显示名称。
    • LOCATION：保存的查询的位置。
    • VISIBILITY：设置为 private 或 shared。
    • SQL_QUERY：SQL 查询。如果单反引号 (`) 封装了路径或路径中的字段，则必须对这些反引号进行转义：
          "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"

      或

          "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"

      当路径元素包含句点 (.) 字符时，需要使用反引号 (`)。

    • ID：保存的查询的 ID。此 ID 是用于描述、更新或删除保存的查询的命令的必需输入。如果您在创建已保存的查询时未提供 ID，则系统会生成一个数字 ID。
    • DESCRIPTION：查询的文本说明。可选。
    • PROJECT_ID：项目的标识符。

    执行 gcloud logging saved-queries create 命令：

    Linux、macOS 或 Cloud Shell

    gcloud logging saved-queries create --display-name=DISPLAY_NAME \
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (PowerShell)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME `
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (cmd.exe)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    以下是命令中提供的 ID 为 my-saved-query 时的响应示例：

    Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].

    对 create 命令的响应会列出查询的完整名称，其中包括查询的 ID。查询 ID（在本示例中为 my-saved-query）是 Google Cloud CLI 命令的必需输入，用于描述、删除或更新已保存的查询。

  2. 如需检查已保存的查询，请运行以下命令：

     gcloud logging saved-queries list --location=- --project=PROJECT_ID

    在上面的表达式中，位置的值为连字符 (-)，它充当通配符。您还可以提供具体位置。

您可以使用 Google Cloud CLI 命令删除、列出、描述和更新已保存的查询。如需了解详情，请参阅 gcloud logging saved-queries 概览。

REST

您可以使用 Cloud Logging API 保存查询。如需保存查询，请使用 savedQueries.create 方法。

如需执行此方法，请执行以下操作：

  1. 选择 savedQueries.create。
  2. 在参考页面上，使用 APIs Explorer 发出命令。您必须指定 opsAnalyticsQuery 字段。

以下示例展示了包含 SavedQuery 实例的请求正文示例：

{
   "parent": "projects/my-project/locations/global"
   "saved_query":
   {
      "ops_analytics_query":
      {
         "sql_query_text" :
            "SELECT
            timestamp, log_name, severity, json_payload, resource, labels
            FROM
            `VIEW`
            WHERE
            timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
            ORDER BY timestamp ASC
            LIMIT 100"
      }
   "visibility": "PRIVATE"
   }
}

共享查询

您可以与有权访问您的Google Cloud 项目的所有用户共享已保存的查询。不过，主账号的 IAM 角色决定了查询是否可以运行以及查询返回的数据。

控制台

在排查问题或看到异常结果时，您可能需要与团队成员共享查询及其结果。在 Observability Analytics 页面上查看查询结果时，您可以复制一个网址，该网址在打开后会显示您运行的查询及其结果。

如需与团队成员共享查询和结果，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Observability Analytics 页面：

    前往 Observability Analytics

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

  2. 在查询窗格中填充查询，然后点击运行查询。

    您可以通过以下方式填充查询窗格：输入新查询、从最近标签页中选择查询或是从已保存标签页中选择查询。

  3. 点击 共享链接。

  4. 将链接发送给您的团队成员。

    您的团队成员打开链接后，系统会打开 Observability Analytics 页面并显示查询，但不会运行查询。您的队友必须手动运行查询。

    当查询在 BigQuery 引擎上运行，且查询的资源不在同一所有权边界内时，Observability Analytics 页面会显示警告对话框。所有权边界由多种因素决定，其中一种因素是查询所用资源的层次结构。

    如需成功打开该网址，您的团队成员在 Google Cloud 项目中的 IAM 角色必须包含查看可观测性分析页面所需的权限。

gcloud

如果您想创建可供他人运行的保存的查询，请将 visibility 字段的值设置为 shared：

--visibility=shared

如需更改现有已保存查询的公开范围，请使用 update 命令。如需详细了解可用命令，请参阅 gcloud logging saved-queries 概览。

REST

您可以使用 Logging API 创建共享查询，具体方式是使用 savedQueries.create 方法，并在 visibility 字段中指定值 SHARED。如需了解详情，请参阅 savedQueries.create 参考页面。

查看和运行最近或已保存的查询

如需查看或重新运行查询，请选择 Observability Analytics 页面上的最近标签页，然后找到相应查询：

  • 如需运行查询，请点击运行。
  • 如需查看查询，请使用 更多选项菜单中的选项。

如需查看、修改或运行已保存的查询，请选择 Observability Analytics 页面上的已保存标签页，然后找到相应查询：

  • 如需运行查询，请点击运行。
  • 如需修改、查看或删除查询，请使用 更多选项菜单中的选项。

后续步骤