配置自定义索引编制

本文档介绍了如何将已编入索引的 LogEntry 字段添加到 Cloud Logging存储分区 更快地查询日志数据。

概览

查询性能对任何日志记录解决方案都至关重要。随着工作负载规模的扩大 相应日志量会不断增加，将最常用的日志数据编入索引可以 缩短查询时间。

为了提高查询性能，Logging 会自动将 以下 LogEntry 字段：

• resource.type
• resource.labels.*
• logName
• 严重程度
• 时间戳
• insertId
• operation.id
• trace
• httpRequest.status
• labels.*
• split.uid

除了 Logging 自动编入索引的字段外，您还可以 还可以指示日志存储桶将其他 LogEntry 字段编入索引，方法是： 该存储桶的自定义索引。

例如，假设您的查询表达式经常包含字段 jsonPayload.request.status。您可以为存储桶配置自定义索引 包含 jsonPayload.request.status；任何后续查询 该存储桶的数据会引用 jsonPayload.request.status 数据（如果查询表达式包含该字段）。

通过使用 Google Cloud CLI 或 Logging API，您可以添加自定义 现有或新日志存储分区的索引。选择更多字段时 要添加到自定义索引中，请注意以下限制：

• 每个自定义索引最多可以添加 20 个字段。
• 配置或更新存储桶的自定义索引后，您必须等待一小时，以便更改应用于查询。此延迟时间可确保查询结果正确无误，并接受过去写入的日志。
• 日志记录会在创建或更改索引后，将自定义索引应用于存储在日志存储分区中的数据；对自定义索引所做的更改不会向日志应用回溯。

准备工作

在开始配置自定义索引之前，请执行以下操作：

• 确认您使用的是最新版 gcloud CLI。如需了解详情，请参阅 管理 Google Cloud CLI 组件。

• 验证您是否拥有具有以下权限的 Identity and Access Management 角色：

  • roles/logging.admin
  • roles/logging.configWriter

  有关这些角色的详细信息，请参阅 使用 IAM 进行访问权限控制。

定义自定义索引

对于添加到存储桶的自定义索引中的每个字段，您都需要定义两个属性：字段路径和字段类型：

• fieldPath：描述 Cloud Logging 中 LogEntry 字段的特定路径。 日志条目。例如 jsonPayload.req_status。
• type：表示字段是字符串类型还是整数类型。可能的值包括 INDEX_TYPE_STRING 和 INDEX_TYPE_INTEGER。

可通过创建新存储桶或通过 更新现有存储桶如需详细了解如何配置存储分区 请参阅配置日志存储分区。

如需在创建存储桶时配置自定义索引，请执行以下操作：

gcloud

使用 gcloud logging buckets create 命令并设置 --index 标志：

gcloud logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

示例命令：

gcloud logging buckets create int_index_test_bucket \
--location=global \
--description="Bucket with integer index" \
--index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

如需创建存储桶，请使用 projects.locations.buckets.create（在 Logging API。请按以下步骤准备方法的参数：

1. 将 parent 参数设置为要在其中创建存储桶的资源：projects/PROJECT_ID/locations/LOCATION

   变量 LOCATION 是指要在其中存储日志的区域。

   例如，如果要在 Cloud Storage 中为项目 my-project 创建存储桶， 在 asia-east2 区域，您的 parent 参数应如下所示： 此内容：projects/my-project/locations/asia-east2

2. 设置 bucketId 参数；例如 my-bucket。

3. 在 LogBucket 请求正文中，配置 IndexConfig 对象 以创建自定义索引。

4. 调用 projects.locations.buckets.create 以创建存储桶。

如需更新现有存储桶以包含自定义索引，请执行以下操作：

gcloud

使用 gcloud logging buckets update 命令并设置 --add-index 标志：

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

示例命令：

gcloud logging buckets update \
int_index_test_bucket \
--location=global \ --add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

使用 Logging API 中的 projects.locations.buckets.patch。在 LogBucket 请求正文时，请将 IndexConfig 对象配置为 添加要编入索引的 LogEntry 字段。

删除自定义编入索引的字段

如需从存储桶的自定义索引中删除字段，请执行以下操作：

gcloud

使用 gcloud logging buckets update 命令并设置 --remove-indexes 标志：

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=INDEX_FIELD_NAME

示例命令：

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

使用 Logging API 中的 projects.locations.buckets.patch。在 LogBucket 请求正文中，从 IndexConfig 对象中移除 LogEntry 字段。

更新已编入索引的自定义字段的数据类型

如果您需要修正已编入索引的自定义字段的数据类型，请执行以下操作：

gcloud

使用 gcloud logging buckets update 命令并设置 --update-index 标志：

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

示例命令：

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

使用 Logging API 中的 projects.locations.buckets.patch。在 LogBucket 请求正文中，更新 IndexConfig 对象，为 LogEntry 字段提供正确的数据类型。

更新已编入索引的自定义字段的路径

如果您需要修正已编入索引的自定义字段的字段路径，请执行以下操作：

gcloud

使用 gcloud logging buckets update 命令并设置 --remove-indexes 和 --update-index 标志：

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

示例命令：

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status_old_path \
--add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER

API

使用 Logging API 中的 projects.locations.buckets.patch。在 LogBucket 请求正文，更新 IndexConfig 对象以提供 LogEntry 字段的正确字段路径。

列出存储桶的所有编入索引的字段

如需列出存储桶的详细信息（包括其自定义编入索引的字段），请执行以下操作：

gcloud

使用 gcloud logging buckets describe 命令：

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

示例命令：

gcloud logging buckets describe indexed-bucket \
--location global

API

使用 Logging API 中的 projects.locations.buckets.get。

清除自定义编入索引的字段

如需从存储桶中移除所有编入索引的自定义字段，请执行以下操作：

gcloud

使用 gcloud logging buckets update 命令并添加 --clear-indexes 标志：

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--clear-indexes

示例命令：

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--clear-indexes

API

使用 Logging API 中的 projects.locations.buckets.patch。在 LogBucket 请求正文，删除 IndexConfig 对象。

查询和查看编入索引的数据

要查询包含在自定义索引字段中的数据，请限制 对包含自定义编入索引字段的存储桶的查询，并指定 相应的日志视图：

gcloud

如需从日志存储桶读取日志，请使用 gcloud logging read 命令并添加 LOG_FILTER可包含 编入索引的数据：

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID

API

如需从日志存储桶读取日志，请使用 entries.list 方法。设置 resourceNames 以指定相应的存储桶和日志视图，并设置 filter 以选择已编入索引的数据。

如需详细了解过滤语法，请参阅 日志记录查询语言。

索引和字段类型

配置自定义字段索引编制的方式可能会影响日志的存储方式 日志存储分区中的数据以及处理查询的方式。

写入时

Logging 会尝试对 存储在日志存储分区中。

编入索引的字段按类型进行排列，这会影响 日志条目。当日志条目存储在日志存储桶中时， 系统将使用下列规则根据索引类型评估日志字段：

• 如果某个字段的类型与索引的类型相同，则系统会将该数据添加到 索引一字不差
• 如果该字段的类型与索引的类型不同，则 Logging 会尝试将其强制转换为索引的类型（对于 例如整数到字符串）。
  • 如果类型强制转换失败，则数据不会被编入索引。类型强制转换成功后，系统会为数据编制索引。

在查询时

为字段启用索引会更改查询该字段的方式。修改者 默认情况下，Logging 会根据以下内容对字段应用过滤条件限制： 每个要评估的日志条目中数据的类型。索引编制时 启用后，系统就会根据 索引中。为字段添加索引会强制为该字段创建架构。

为存储桶配置自定义索引时，架构匹配行为 会有所不同：

• 字段的来源数据类型与该字段的索引类型不匹配。
• 用户对该字段应用了限制条件。

请考虑以下 JSON 载荷：

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

现在，将此过滤条件应用于以下每个维度：

jsonPayload.value > 20

如果 jsonPayoad.value 字段缺少自定义索引，则 Logging 采用灵活的类型匹配：

• 对于“A”，Logging 会观察到“value”键的值实际上是整数，并且约束条件“20”可以转换为整数。然后，Logging 会评估 12345 > 20 并返回 “true”因为在数值上就是这样。

• 对于“B”，Logging 会发现“value”键的值实际上是字符串。然后，它会评估 "3" > "20" 并返回“true”， 因为按字母数字排序。

如果自定义索引中包含字段 jsonPayload.value，则 Logging 使用索引（而不是 常规日志记录逻辑行为变化：

• 如果索引是字符串类型的，则所有比较都是字符串比较。
  • “A”因为“12345”不大于“20” 。“B”因为字符串“3”大于 而不是“20”。
• 如果索引是整数类型的，则所有比较都是整数比较。
  • “B”条目不匹配，因为“3”在数字上不大于“20”。由于“12345”大于“20”，因此“A”条目匹配。

这种行为差异很细微，在定义和更改 自定义索引

过滤极端情况

对于 jsonPayload.value 整数类型索引，假设字符串值为 已过滤：

jsonPayload.value = "hello"

如果查询值无法强制转换为索引类型，系统会忽略该索引。

不过，假设对于字符串类型索引，您传递了一个整数值：

jsonPayload.value > 50

A 和 B 都不匹配，因为“12345”或“3”字母数字上大于 而不是“50”。