此页面由 Cloud Translation API 翻译。

配置分布指标

本页面介绍如何使用 Google Cloud 控制台、Logging API 和 Google Cloud CLI 创建基于日志的分布类型指标。如需全面了解基于日志的指标，请参阅基于日志的指标概览。

概览

分布指标既需要使用过滤条件来选择相关的日志条目，也需要使用值提取器来获取分布的数值。值提取器与用户定义的标签所用的类型相同。

分布指标用于记录已提取值在直方图分区中的统计分布情况。分布指标不会单独记录已提取值，而是会记录这些值在已配置分区中的分布情况，以及相关值的数量、平均值和方差和。您可以在分布中使用直方图分区的默认布局，也可以微调分区边界以大致捕获这些值。

如需详细了解如何查看和解读分布指标，请参阅分布指标。

准备工作

如需使用基于日志的指标，您必须拥有一个已启用结算功能的 Google Cloud 项目：
确保您的 Identity and Access Management 角色包含创建和查看基于日志的指标以及创建提醒政策所需的权限。如需了解详情，请参阅针对基于日志的指标的权限。

创建分布指标

该指标计算由您提供的过滤条件标识的日志条目数。您可以在过滤器中使用正则表达式，我们建议您添加资源类型。过滤条件的长度不能超过 20,000 个字符。

不要将敏感信息放入过滤器。过滤器将被视为服务数据。

控制台

如需在 Google Cloud 项目的 Google Cloud 控制台中创建基于日志的计数器指标，请按以下步骤操作：

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择基于日志的指标：
前往基于日志的指标
点击创建指标。此时会显示创建日志指标面板。
设置指标类型：选择分布。
在详细信息部分中设置以下字段：
- 日志指标名称：选择一个在 Google Cloud 项目中基于日志的指标中具有唯一性的名称。您需遵循一些命名限制；如需了解详情，请参阅问题排查。
- 说明：输入此指标的说明。
- 单位：（可选）对于分布指标，您可以选择输入单位，例如 s、ms 等。如需了解详情，请查看 MetricDescriptor 的 unit 字段。
在过滤器选择部分中，定义指标过滤器。
1. 使用选择日志范围来选择过滤条件是针对所有 Google Cloud 项目日志，还是仅针对特定存储桶中的日志。
2. 使用日志记录查询语言创建一个过滤器，用于仅收集要在指标中计数的日志条目。您还可以使用正则表达式来创建指标的过滤器。
3. 字段名称：输入包含分布值的日志条目字段。系统会在您输入时即时向您提供选项。例如：
```
 protoPayload.latency
```
4. 正则表达式：（可选）如果字段名称始终包含可转换为 double 类型的数值，则您可以将此字段留空。否则，请指定用于从该字段值中提取数字分布值的正则表达式。
  
  示例。假设您的 latency 日志条目字段包含一个数字，后跟表示毫秒的 ms。以下正则表达式用于选择不含单位后缀的数字：
```
([0-9.]+)
```
  英文括号（称为正则表达式捕获组）用于标识文本匹配中将要提取的部分。如需了解详情，请参阅使用正则表达式。
- 更多（直方图分区）：（可选）点击高级可打开您可以用来指定自定义分区布局的表单的一部分。如果您未指定分区布局，则系统会提供默认分区布局。如需了解详情，请参阅本页面上的直方图分区。
1. 如需查看哪些日志条目与您的过滤条件匹配，请点击预览日志。
（可选）在标签部分中添加标签。如需了解如何创建标签，请参阅创建标签。
点击创建指标，以创建指标。

gcloud

如需创建基于日志的分布类型指标，请创建一个文件，其中包含 JSON 或 YAML 格式的 LogMetric 定义表示形式。然后，使用以下命令从文件中读取配置：

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

如需了解如何描述分布的直方图分区，请参阅直方图分区。

API

要创建分布指标，请使用 Logging API 的 projects.metrics.create 方法。您可以试用 APIs Explorer 中的方法。请按以下步骤准备方法的参数：

将 parent 字段设置为要在其中创建指标的项目或存储桶：
- 对于项目级范围的基于日志的指标，请指定项目：
```
projects/PROJECT_ID
```
- 对于存储桶级基于日志的指标，请指定存储桶：
```
projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
```

将请求正文设置为 LogMetric 对象。以下是分布指标的示例对象。

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

备注：

您需遵循一些命名限制；要了解详情，请参阅问题排查。
metricDescriptor：一个 MetricDescriptor 对象。metricKind 必须为 DELTA。valueType 必须为 DISTRIBUTION。

直方图分区

分布指标包括一个直方图，用于计算指定范围（分区）内的值的数量。一个分布指标中最多可以有 200 个分区。

每个分区有两个边界值（L 和 H），分别用来定义相应分区所覆盖的最小值和最大值。分区的宽度为 H - L。由于分区之间不能存在间隙，因此一个分区的下边界即是前一个分区的上边界，依此类推。因此，边界不会落入多个分区中，一个分区包括其下边界；其上边界则属于下一个分区。

您可以按递增顺序列出各个分区之间的边界值，以此来指定所有分区布局。第一个分区是下溢分区，该分区计算小于第一个边界值的值的数量。最后一个分区是上溢分区，该分区计算大于或等于最后一个边界值的值的数量。其他分区计算大于或等于其下边界值且小于其上边界值的值的数量。如果有 n 个边界值，则有 n + 1 个分区。nn除下溢分区和上溢分区之外，存在 n - 1 个有限分区。n-1

您可以通过以下三种不同的方式为分布指标指定直方图分区间的边界。您可以指定边界值公式，也可以列出边界值：

Linear(offset, width, i)：每个分区具有相同的宽度。边界值为 offset + width * i，其中 i=0、1、2、...、N。如需详细了解线性分区，请参阅 API 参考文档。
Exponential(scale, growth_factor, i)：值越大，分区宽度也越大。边界值为 scale * growth_factorⁱ，其中 i=0,1,2,...,N。如需详细了解指数桶，请参阅 API 参考文档。
Explicit：由您在 bounds 数组中列出分区的所有边界值。分区 i 的边界如下：i

上限：bounds[i]（0 <= i < N-1）
下限：bounds[i - 1]（1 <= i < N）
iiiiii

如需详细了解显式分区，请参阅 API 参考。

以下部分介绍了如何指定直方图分区。

控制台

当您创建分布指标并在指标编辑器表单中点击更多后，系统将打开直方图分区子菜单。线性分区布局的子表单如下所示：

直方图分区

线性分区：按如下所示填写直方图分区表单。

类型：线性
起始值 (a)：第一个有限分区的下边界。a此值在 API 中称为 offset。
分区数 (N)：有限分区数。此值必须大于或等于 0。
分区宽度 (b)：每个有限分区中的上限和下限之间的差值。b该值必须大于 0。

例如，如果起始值为 5，分区数为 4，分区宽度为 15，则分区范围如下所示：

(-INF, 5)、[5, 20)、[20, 35)、[35, 50)、[50, 65)、[65, +INF)

显式分区：按如下所示填写直方图分区表单：

类型：显式
边界 (b)：有限分区的边界值的英文逗号分隔列表。b此列表也决定了分区的数量及其宽度。

例如，如果边界值列表是：

0, 1, 2, 5, 10, 20

则存在五个范围如下的有限分区：

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

指数分区：按如下所示填写直方图分区表单：

类型：指数
分区数 (N)：有限分区总数。该值必须大于 0。
线性比例 (a)：分区的线性比例。a该值必须大于 0。
指数增长因数 (b)：分区的指数增长因数。b该值必须大于 1。

例如，如果 N = 4，a = 3，b = 2，则分区范围如下所示：

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

如需详细了解存储分区，请参阅 Cloud Monitoring API 中的 BucketOptions。

API

可选分区布局由提供给 projects.metrics.create 的 LogMetric 对象中的 bucketOptions 字段指定。如需查看完整的 LogMetric 对象，请参阅本页面中的创建分布指标。对于分区布局，新增的内容如下所示：

线性分区：

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

上一个示例创建了以下分区：

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

显式分区：边界会单独列出。

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

上一个示例创建了以下分区：

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

指数分区：边界值为 scale * growthFactor ^ i，其中 i = 0、1、2、...、numFiniteBuckets

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

上一个示例创建了以下分区：

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

新指标延迟情况

您的新指标会立即显示在指标列表和相关的 Monitoring 菜单中。不过，指标最多可能需要一分钟才能开始收集匹配日志条目的数据。

检查分布指标

如需列出 Google Cloud 项目中用户定义的基于日志的指标，或检查 Google Cloud 项目中的特定指标，请执行以下操作：

控制台

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择基于日志的指标：
前往基于日志的指标
在用户定义的指标窗格中，您会看到当前 Google Cloud 项目中用户定义的基于日志的指标：
如需查看基于日志的指标中的数据，请点击指标行中的菜单，然后选择在 Metrics Explorer 中查看。

gcloud

如需列出 Google Cloud 项目中用户定义的基于日志的指标，请使用以下命令：

gcloud logging metrics list

如需在 Google Cloud 项目中显示用户定义的基于日志的指标，请使用以下命令：

gcloud logging metrics describe METRIC_NAME

如需获取帮助，请使用以下命令：

gcloud logging metrics --help

您无法通过 Google Cloud CLI 读取指标的时序数据。

API

列出指标

如需列出 Google Cloud 项目中用户定义的基于日志的指标，请使用 projects.metrics.list API 方法。按如下所示填写方法的参数：

parent：Google Cloud 项目的资源名称：projects/PROJECT_ID。
pageSize：最大结果数。
pageToken：获取下一页结果。如需了解如何使用页面令牌，请参阅 projects.metrics.list。

检索指标定义

要检索单个用户定义的基于日志的指标，请使用 projects.metrics.get API 方法。按如下所示填写方法的参数：

metricName：指标的资源名称：
```
projects/PROJECT_ID/metrics/METRIC_ID
```

读取指标数据

如需读取基于日志的指标中的时序数据，请使用 Cloud Monitoring API 中的 projects.timeseries.list。如需详细了解时序数据，请参阅读取时序。

如需读取单个用户定义的基于日志的指标，请使用此指标类型和标识符填充该方法的参数：

logging.googleapis.com/user/METRIC_ID

更新分布指标

您可以修改用户定义的基于日志的指标，以更改其说明、过滤条件以及指标中引用的字段的名称。您可以为指标添加新标签，也可以更改用于提取指标及其标签值的正则表达式。如果您使用的是存储桶级指标，还可以更新指标的分桶。

您无法更改用户定义的基于日志的指标或其标签的名称或类型，也无法删除基于日志的指标中的现有标签。

如需修改基于日志的指标，请执行以下操作：

控制台

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择基于日志的指标：
前往基于日志的指标
在要修改的基于日志的指标的菜单中，点击修改指标。
更改指标中允许更改的项目。
点击更新指标。

gcloud

使用 Google Cloud CLI 更改计数器指标的说明、过滤查询和存储桶。您可以一次性更新任意或所有字段。

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

如果您更改与存储桶级指标关联的存储桶，则在更改之前收集的任何指标数据都将不再反映当前配置。为上一个存储桶收集的指标数据不会移除。

如需更新分布指标或其他计数器指标字段（不包括 METRIC_NAME），请创建一个文件，以 JSON 或 YAML 格式包含修改后的 LogMetric 规范。然后，使用 --config-from-file 字段调用 update 命令，并将 FILENAME 替换为您的 JSON 或 YAML 文件的名称，从而更新指标：

gcloud logging update METRIC_NAME --config-from-file FILENAME

如需了解详情，请使用以下命令：

gcloud logging metrics update --help

API

要修改基于日志的指标，请使用 API 中的 projects.metrics.update 方法。按如下方式设置字段：

metricName：指标的完整资源名称：

projects/PROJECT_ID/metrics/METRIC_ID

例如：

projects/my-gcp-project/metrics/my-error-metric

在请求正文中，添加与现有指标完全相同（要更改或新增的内容除外）的 LogMetric 对象。

删除分布指标

如需删除用户定义的基于日志的指标，请执行以下操作：

控制台

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择基于日志的指标：
前往基于日志的指标
选择您要删除的指标，然后点击删除。

或者，在要删除的基于日志的指标的菜单中点击删除指标。

gcloud

使用以下命令删除当前 Google Cloud 项目中用户定义的基于日志的指标：

gcloud logging metrics delete METRIC_NAME

For more details, use the following command:

gcloud logging metrics delete --help

API

要删除用户定义的基于日志的指标，请使用 API 中的 projects.metrics.delete 方法。

此外，在 Google Cloud 控制台的基于日志的指标页面中，基于日志的指标界面的用户定义的指标窗格也提供了更多功能，可帮助您管理 Google Cloud 项目中用户定义的指标。如需了解详情，请参阅用户定义的指标窗格。