创建分布指标

本页面介绍了如何使用 GCP Console 和 Stackdriver Logging API 创建分布类型的基于日志的指标

概览

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

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

创建分布指标

Logging 控制台

请按照以下步骤在 GCP Console 中创建基于日志的指标:

  1. 点击 GCP Console 左侧导航列表中的 Stackdriver Logging > 基于日志的指标,或点击以下按钮:

    转到“日志查看器”

  2. 使用页面顶部的下拉菜单选择一个项目。

  3. 点击页面顶部的创建指标。此时,您可以在页面右侧看到指标编辑器,还可以在左侧看到显示了日志的查看器面板:

    创建分布指标

  4. 在查看器面板中,创建一个过滤条件,用于仅显示要在指标中计数的日志条目。

    日志条目上方的下拉菜单中提供了基本过滤条件。或者,您可以点击搜索栏右侧的下拉菜单并选择转换为高级过滤条件,以访问高级过滤条件界面。

    如需了解详情,请参阅界面

  5. 指标编辑器面板中,设置以下字段:

    • 名称:选择对于项目中基于日志的指标而言唯一的名称。您需遵循一些命名限制;要了解详情,请参阅问题排查
    • 说明:对指标进行说明。
    • 标签:(可选)针对每个标签点击添加一项可添加标签。如需详细了解如何定义标签,请参阅基于日志的指标标签
    • 单位:(可选)对于分布指标,您可以选择输入 sms 等单位。如需了解详情,请参阅 MetricDescriptorunit 字段。
    • 类型分布
    • 字段名称:输入包含分布值的日志条目字段。系统会在您输入时即时向您提供选项。例如:

      jsonPayload.latency
      
    • 提取表达式:(可选)如果字段名称始终包含可转换为 double 类型的数值,则您可以将此字段留空。否则,请指定用于从该字段值中提取数字分布值的正则表达式。构建菜单可用于以交互方式构建和验证正则表达式。

      示例。假设您的 latency 日志条目字段包含一个数字,后跟表示毫秒的 ms。以下正则表达式用于选择不含单位后缀的数字:

      ([0-9.]+)ms
      

      英文括号(称为正则表达式捕获组)用于标识文本匹配中将要提取的部分。如需详细了解正则表达式,请参阅 RE2 语法

    • 更多(直方图分区):(可选)点击更多可打开您可以用来指定自定义分区布局的表单的一部分。如果您未指定分区布局,则系统会提供默认分区布局。如需了解详情,请参阅本页面上的直方图分区

  6. 点击创建指标

Logging API

要创建分布指标,请使用 Stackdriver Logging API 的 projects.metrics.create 方法。您可以在 [APIs Explorer] [apis-explorer-create] 中试用该方法。请按以下步骤准备方法的参数:

  1. parent 字段设置为要在其中创建指标的项目:

    projects/[PROJECT_ID]
    
  2. 将请求正文设置为 LogMetric 对象。以下是分布指标的对象的一个示例:

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_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.",
            }
          ]
      },
    }
    

分布指标说明:

  • 您需遵循一些命名限制;要了解详情,请参阅问题排查

  • metricDescriptorMetricDescriptor 对象。metricKind 必须是 DELTAvalueType 必须是 DISTRIBUTION

直方图分区

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

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

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

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

  • Linear(offset, width, i):每个分区具有相同的宽度。i = 0、1、2、…、N 时,边界为 offset + width * i。如需详细了解线性分区,请参阅 API 参考

  • Exponential(scale, growth_factor, i):值越大,分区宽度也越大。i = 0、1、2、…、N 时,边界为 scale * growth_factor^i。如需详细了解指数分区,请参阅 API 参考

  • Explicit:由您在 bounds 数组中列出分区的所有边界值。分区 i 的边界如下:

    上限:bounds[i](0 <= i < N-1 时)
    下限:bounds[i - 1](1 <= i < N 时)

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

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

Logging 控制台

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

直方图分区

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

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

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

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

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

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

例如,如果边界值列表是:

0, 1, 2, 5, 10, 20

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

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

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

  • 类型指数
  • 分区数 (N):有限分区总数。该值必须大于 0。

  • 线性比例 (a):分区的线性比例。该值必须大于 0。

  • 指数增长因数 (b):分区的指数增长因数。该值必须大于 1。

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

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

如需详细了解分区,请参阅 Stackdriver Monitoring API 中的 BucketOptions

Logging API

可选分区布局由提供给 projects.metrics.createLogMetric 对象中的 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]

新指标延迟情况

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

检查分布指标

要列出 GCP 项目中基于日志的指标,或检查项目中的特定指标,请执行以下操作:

Logging 控制台

点击以下按钮即可转到基于日志的指标页面,其中列出了当前项目中所有基于日志的指标:

转到“基于日志的指标”

要查看基于日志的指标中的数据,请从指标列表右侧的菜单中选择在 Metric Explorer 中查看

Logging API

列出指标

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

  • parent:项目 projects/[PROJECT_ID] 的资源名称。
  • pageSize:最大结果数。
  • pageToken:获取下一页结果。请参阅 projects.metrics.list

检索指标定义

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

  • metricName:指标的资源名称:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

读取指标数据

要读取基于日志的指标中的时间序列数据,请使用 Stackdriver Monitoring API 中的 projects.timeseries.list。如需了解详情,请参阅读取时间序列。以下是基于日志的指标所需的信息:

  • 指标类型为 logging.googleapis.com/user/[METRIC_ID]

Cloud SDK

要列出项目中用户定义的基于日志的指标,请使用以下命令:

gcloud logging metrics list

要显示项目中用户定义的基于日志的指标,请使用以下命令:

gcloud logging metrics describe [METRIC_NAME]

如需了解详情,请使用以下命令:

gcloud logging metrics --help

您无法通过 Cloud SDK 读取指标的时间序列数据。

更新分布指标

您可以通过更新基于日志的指标来更改指标中引用的字段的说明、过滤条件和名称。您可以向指标添加新标签,还可以更改用于提取指标及其标签的值的正则表达式。

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

要修改或更新基于日志的指标,请执行以下操作:

Logging 控制台

  1. 转到基于日志的指标页面:

    转到“基于日志的指标”

  2. 在要修改的基于日志的指标右侧的菜单中,点击修改指标

  3. 仅更改指标中允许更改的项目。

  4. 点击完成

Logging API

要修改或更新基于日志的指标,请使用该 API 中的 projects.metrics.update 方法。按如下所示设置字段:

  • metricName:指标的完整资源名称:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    例如:

    projects/my-gcp-project/metrics/my-error-metric
    
  • 在请求正文中,添加与现有指标完全相同(要更改或新增的内容除外)的 LogMetric 对象。

Cloud SDK

您只能使用 Cloud SDK 更改现有指标的说明和过滤条件。

要更新基于日志的指标,请使用以下命令。您可以指定其中一个或两个标志:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

如需了解详情,请使用以下命令:

gcloud logging metrics update --help

删除分布指标

要删除基于日志的指标,请执行以下操作:

Logging 控制台

  1. 转到基于日志的指标页面:

    转到“基于日志的指标”

  2. 选择要删除的指标,然后点击页面顶部的删除

    或者,在要删除的基于日志的指标右侧的菜单中,点击删除指标

Logging API

使用该 API 中的 projects.metrics.delete 方法。

Cloud SDK

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

gcloud logging metrics delete [METRIC_NAME]

如需了解详情,请使用以下命令:

gcloud logging metrics delete --help

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Stackdriver Logging
需要帮助?请访问我们的支持页面