为基于日志的指标配置标签

本文档介绍了基于日志的指标标签，并说明了如何对基于日志的指标创建和使用标签。

如果您熟悉标签，则可以直接转到本页面上的创建标签部分。

基于日志的指标的标签概览

通过标签，基于日志的指标可以包含多个时序，每个时序一个 标签值的组合。所有基于日志的指标都附带若干默认标签。

通过指定提取器表达式，您可以在计数器类型和分布类型指标中创建更多用户定义的标签。提取器表达式告知 Cloud Logging 如何从日志条目中提取标签值。您可以将标签的值指定为以下任一值：

  • LogEntry 对象中已命名字段的全部内容。
  • 命名字段中与正则表达式 (regexp) 相匹配的一部分。

您可以从 httpRequest.status 等 LogEntry 内置字段中提取标签，也可以从负载字段 textPayload、jsonPayload 或 protoPayload 中提取标签。

如需了解正则表达式，请参阅 RE2 语法。

请勿在提取器表达式中放置敏感信息，也不得将敏感数据提取到标签中。这些数据会被视为服务数据。

用户定义的标签的限制

以下限制适用于用户定义的标签：

  • 最多可为每个指标创建 10 个用户定义的标签。

  • 标签一经创建便无法删除。

    • 您可以修改已创建标签的提取器表达式和说明。

    • 您不能更改已创建标签的名称或值类型。

  • 仅保留标签值的前 1024 个字符。

  • 每个基于日志的指标最多只能有约 30000 个活跃的时序，这取决于每个标签（包括默认标签）的可能值的数量。

    例如，如果您的日志条目来自 100 项资源（例如虚拟机实例），而您定义了具有 20 个可能值的标签，那么您的指标最多可能有 2000 个时间序列。

如果您拥有的时间序列或数据点过多，则您的费用将会升高，并且您的运行可能会受到限制。如需详细了解基于日志的指标的费用，请参阅“Cloud Monitoring 价格：需付费的指标”。如需了解应用于基于日志的指标的限制，请参阅“配额和限制：基于日志的指标”和排查基于日志的指标的问题。

默认标签

所有基于日志的指标都附带若干预定义标签。

  • 资源标签：所有指标均使用受监控的资源对象来标识时序数据的来源。每种资源类型都包括一个类型名称和一个或多个标签。资源类型的示例包括虚拟机实例、Cloud SQL 数据库和负载均衡器等。

    资源及其标签与 Cloud Monitoring 中的其他指标标签分开列出，但两者具有相同的效果：它们会在指标中创建更多时间序列。如需了解详情，请参阅指标、时间序列和资源。

  • log：此标签包含日志条目中 logName 字段的 LOG_ID 部分的值。

  • severity：此标签包含日志条目中 severity 字段的值。默认情况下，severity 标签仅在基于日志的系统指标中提供。

示例：使用 Metrics Explorer

来自 Metrics Explorer 的以下屏幕截图显示了某个（基于日志的）系统指标的标签。在过滤条件文本框内点击即可获取标签列表：

Metrics Explorer

该屏幕截图显示了以下信息：

  • Metrics Explorer 使用 logging/log_entry_count 指标和 gce_instance 资源类型（Compute Engine 虚拟机实例）的时间序列。

    此指标还包含其他资源类型的时间序列，但 Metrics Explorer 一次只允许您查看一种资源类型。

  • gce_instance 资源类型有三个资源标签：project_id、instance_id 和 zone。

  • 该指标有两个指标标签：log 和 severity。用户定义的标签也会显示在此部分中。

创建标签

您在创建指标的同时创建用户定义的标签。计数器指标和分布指标都可以包含标签。您不能为（基于日志的）系统指标添加标签。

控制台

  1. 创建基于日志的指标时，创建日志指标面板会包含一个用于添加标签的选项。

  2. 点击添加标签。

    提示：要查看日志条目内的字段和值，请执行以下操作：

    1. 在过滤器选择部分中，点击预览日志。
    2. 在查看日志窗格中，选择一个日志条目并点击其旁边的展开箭头 。
    3. 点击展开嵌套字段。

  3. 在标签部分中设置以下字段：

    1. 标签名称：输入标签名称。例如 ID。

      该名称必须符合以下条件：

      • 长度不超过 100 个字符。
      • 匹配正则表达式 [a-zA-Z][a-zA-Z0-9_]*。
      • 不能只包含字符串“log”。

    2. 说明：对标签进行说明。尽可能具体地说明预期日志值的格式，例如 Instance number。

    3. 标签类型：选择字符串、布尔值或整数。

    4. 字段名称：输入包含标签值的日志条目字段名称。系统会在您输入时即时向您提供选项。在此示例中，该字段为：

      labels."compute.googleapis.com/resource_id"

    5. 正则表达式：如果标签的值包含字段的全部内容，则可以将此字段留空。否则，请指定用于从该字段值中提取标签值的正则表达式捕获组。

      例如，假设该字段通常包含如下文本：

      The instance number is 0123456789; the ID is my-test-instance22

      如果您希望标签值为实例编号，则有许多正则表达式可用来提取正确的编号。例如，在以下表达式中，括号是一个捕获组，用于标识文本将被提取的部分：

      The instance number is ([0-9]+); .*

      如需详细了解正则表达式，请参阅 RE2 语法。

  4. 点击完成，以创建标签。您可以重复上述步骤添加更多标签。

  5. 要完成指标的创建，请点击创建指标。

gcloud

如需创建包含自定义标签的基于日志的指标，您必须创建一个文件，其中包含 JSON 或 YAML 格式的 LogMetric 定义的表示法，包括自定义标签。然后，创建指标 方法是调用带有 --config-from-file 标志的 create 命令， 将 FILENAME 替换为您的 JSON 或 YAML 文件的名称：

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

如需了解详情，请参阅 gcloud logging metrics create。

API

在对 Logging API 的 projects.metrics.create 方法的调用的请求正文中，标签被指定为 LogMetric 对象的一部分。如需了解完整的方法调用，请参阅创建计数器指标或创建分布指标。

对于每一个标签，您必须向 LogMetric 中的 metricDescriptor 和 labelExtractors 字段添加一个细分。

语法如下所示：

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

相应语法元素的含义如下：

  • LABEL_NAME：字符串形式的标签名称。
  • VALUE_TYPE：标签的类型：STRING、BOOL 或 INT64。
  • LABEL_DESCRIPTION：标签的说明。

  • EXTRACTOR_EXPRESSION：一个用于组合日志条目字段名称与可选的正则表达式的字符串。提取器表达式可以是以下各项之一：

    EXTRACT(FIELD)

    REGEXP_EXTRACT(FIELD, REGEXP)

如需详细了解正则表达式，请参阅 RE2 语法。

以下是含有两个标签的示例：

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

如需了解详情，请参阅 LogMetric 类型。