「译文」Prometheus 中的 relabel 是如何工作的？

本文最后更新于：2023年5月6日上午

👉️URL: https://grafana.com/blog/2022/03/21/how-relabeling-in-prometheus-works/

✍️Author: Paschalis Tsilias

📝Description:

Relabeling in Prometheus is a powerful tool that allows you to classify and filter targets and metrics.

Relabel（重新标记）是一个强大的工具，允许你通过重写标签集对 Prometheus 目标 (targets) 和指标 (Metrics) 进行分类和过滤。

这篇文章的目的是解释 Prometheus 的 relabel_config 块的价值，可以在 Prometheus 配置的不同地方找到它，以及它在驯服 Prometheus 指标方面的作用。这里的大部分内容也适用于 Grafana Agent 用户。

作为参考，这里是我们的通过重新标记减少普罗米修斯指标的使用指南。

因此，不再多说，让我们进入正题吧！

Prometheus labels

标签 (Label) 是一组键值对，允许我们描述和组织 Prometheus 指标中实际测量的内容。

例如，在测量 HTTP 延迟时，我们可以使用 label 来记录返回的 HTTP 方法和状态，哪个端点被调用，以及哪个服务器负责请求。

在 Prometheus 中，键值标签对的每个独特组合都被存储为一个新的时间序列，因此标签对于理解数据的 cardinality 至关重要，应避免将无界的值集作为标签。

内部 labels

但是没有标签的指标怎么办？普罗米修斯也为我们提供了一些内部的标签。这些标签以两个下划线开头，并在所有重新标记 (relabel) 步骤应用后被删除；这意味着除非我们明确配置它们，否则它们将不可用。

我们可以使用的这些特殊标签中的一些是

Label name	Description
`__name__`	被刮削（收集、采集）的 Metric 名称
`__address__`	被刮削 target 的 host:port
`__scheme__`	被刮削 target 的 URI scheme
`__metrics_path__`	被刮削 target 的 Metrics endpoint
`__param_<name>`	是传递给目标的第一个 URL 参数的值
`__scrape_interval__`	目标的刮削间隔（实验性的）。
`__scrape_timeout__`	刮削目标超时时间（实验性的）
`__meta_`	由服务发现机制设置的特殊标签集
`__tmp`	特殊的前缀，用于在丢弃标签值之前临时存储它们

那么现在我们明白了各种 relabel_config 规则的输入是什么，我们如何创建一个 relabel 配置？它们到底能用来做什么？

申请 (Application) 的阶段

围绕重新标记规则的一个混乱来源是，它们可以在 Prometheus 配置文件的多个部分找到。

# 刮削配置列表
scrape_configs:
    - job_name: "some scrape job"
    ...
 
    # target relabel 配置列表。
    relabel_configs:
    [- <relabel_config> ... ]

    # metric relabel 配置列表。
    metric_relabel_configs:
    [- <relabel_config> ... ]

# 与远程写入有关的设置。
remote_write:
    url: https://remote-write-endpoint.com/api/v1/push 
    ...

    # 远程写 relabel 配置的列表。
    write_relabel_configs:
    [- <relabel_config> ... ]

原因是重新标记可以应用于指标生命周期的不同部分–从选择我们想搜刮的可用目标，到筛选我们想存储在 Prometheus 时序数据库中的内容，以及发送至一些远程存储的内容。

首先，relabel_configs 键可以作为刮削任务定义的一部分被找到。这些重新标记的步骤是在 刮削发生之前 应用的，并且只能访问由 Prometheus 的服务发现添加的标签。它们允许我们过滤由我们的 SD 机制返回的目标，以及操纵它设置的标签。

一旦目标被定义，metric_relabel_configs 步骤将在刮削后应用，并允许我们选择哪些系列 (series) 的数据被纳入 Prometheus 的存储中。

最后，write_relabel_configs 块在数据被发送到远程端点之前，对其应用重新标记规则。这可以用来过滤具有 high cardinality 的指标或将指标路由到特定的远程写入目标。

基本 `<relabel_config>` 块

一个 <relabel_config> 由七个字段组成。它们是

source_labels
separator (default = ;)
target_label
regex (default = (.*))
modulus
replacement (default = $1)
action (default = replace)

一个 Prometheus 配置可能包含一个重新标记的步骤阵列；它们按照定义的顺序应用于标签集。遗漏的字段采用其默认值，所以这些步骤通常会比较短。

source_labels（源标签列表）和 separator（分离器）

让我们从 source_labels 开始。它期望值为一个或多个标签名称的数组，用来选择各自的标签值。如果我们在 source_labels 数组中提供一个以上的名字，结果将是它们的值的内容，使用提供的 `separator’连接起来。

作为一个例子，考虑以下两个指标

1 2	`my_custom_counter_total{server="webserver01",subsystem="kata"} 192 1644075044000 my_custom_counter_total{server="sqldatabase",subsystem="kata"} 147 1644075044000`

下面的 relabel_config:

1 2	`source_labels: [subsystem, server] separator: "@"`

将提取这些值：

1 2	`kata@webserver01 kata@sqldatabase`

regex（正则）

regex字段期望一个有效的 RE2 正则表达式，用于匹配从source_label和 separator 字段组合中提取的值。该正则表达式支持括号内的捕获组，可以在后面提到。

这个块将匹配我们之前提取的两个值

1
2
3

source_labels: [subsystem, server]
separator: "@"
regex: "kata@(.*)"

然而，下面这个区块将不与之前的标签相匹配，并将中止执行这个特定的重新标注步骤：

1
2
3

source_labels: [subsystem, server]
separator: "@"
regex: "(.*)@redis"

默认的 regex 值是(.*)，所以如果不指定，它将匹配整个输入。

replacement（替换）

如果提取的值与给定的 regex 相匹配，那么 replacement 就会通过执行 regex 替换和利用任何先前定义的捕获组而得到填充。回到我们的提取值，以及像这样的一个块：

source_labels: [subsystem, server]
separator: "@"
regex: "(.*)@(.*)"
replacement: "${2}/${1}"

将导致捕获 @ 符号之前和之后的内容，将它们对调，并用斜线分开。

1 2	`webserver01/kata sqldatabase/kata`

替换的默认值是 $1，所以它将匹配重合词中的第一个捕获组，如果没有指定重合词，则匹配整个提取的值。

target_label（目标 label)

如果 relabel 动作导致一个值被写入某个标签，target_label定义了替换值应该被写入 哪个标签。例如，下面的代码块将设置一个标签，如{env="production"}。

1
2
3

replacement: "production"
target_label: "env"
action: "replace"

同时，接着前面的例子，下面这个重新标记的步骤将把 replacement 值设置为 my_new_label:

- source_labels: [subsystem, server]
  separator: "@"
  regex: "(.*)@(.*)"
  replacement: "${2}/${1}"
  target_label: "my_new_label"
  action: "replace"

结果是：

1 2	`{my_new_label="webserver01/kata"} {my_new_label="sqldatabase/kata"}`

modulus（模数）

最后，modulus 字段期望值是一个正整数。relabel_config 步骤将使用这个数字将 MD5（提取值） % modulus 表达式的结果填充到目标标签中。

可用的 actions（行为）

我们已经走了很长的路，好在我们终于有了进展。现在，我们能用这些积木做什么？它们如何在我们的日常工作中帮助我们？

有七个可供选择的行动，让我们仔细看看。

keep/drop （保留 / 丢弃）

保留和丢弃动作允许我们根据我们的标签值是否与所提供的 relabel 相匹配来过滤掉目标 (targets) 和指标 (Metrics)。

让我们回到我们之前的例子：

1 2	`my_custom_counter_total{server="webserver01",subsystem="kata"} 192 1644075074000 my_custom_counter_total{server="sqldatabase",subsystem="kata"} 14700 1644075074000`

在连接了 subsystem 和 server 标签的内容后，我们可以通过使用下面的块丢弃暴露 webserver-01 的目标。

- source_labels: [subsystem, server]
  separator: "@"
  regex: "kata@webserver"
  action: "drop"

或者，如果我们在一个有多个子系统的环境中，但只想监控 kata，我们可以保留关于它的特定目标或指标，而放弃与其他服务有关的一切：

- source_labels: [subsystem, server]
  separator: "@"
  regex: "kata@(.*)"
  action: keep

在许多情况下，这里是内部标签发挥作用的地方。

例如，你可以只保留特定的 metric 名称：

1
2
3

- source_labels: [__name__]
  regex: “my_custom_counter_total|my_custom_counter_sum|my_custom_gauge”
  action: keep

或者如果你使用 Prometheus 的 Kubernetes 服务发现，你可能想从你的 testing 或 staging命名空间删除所有目标。

1
2
3

- source_labels: [__meta_kubernetes_namespace]
  regex: “testing|staging”
  action: drop

labelkeep/labeldrop（标签保留 / 标签丢弃）

labelkeep 和 labeldrop 动作允许对标签集本身进行过滤。

在前面的例子中，我们可能对跟踪特定的subsystem 标签不感兴趣了。

下面的重新标记将删除所有的{subsystem="<value>"} 标签，但保留其他标签。

1 2	`- regex: "subsystem" action: labeldrop`

当然，我们可以反其道而行之，只保留一套特定的标签，而放弃其他一切：

1 2	`- regex: "subsystem\|server\|shard" action: labelkeep`

我们必须确保在应用 labelkeep 和 labeldrop 规则后，所有的 metrics 仍然是唯一的标签。

replace（替换）

替换是重标规则的默认动作，如果我们没有指定的话；它允许我们用 replacement 字段的内容覆盖一个标签的值。

正如我们之前看到的，下面的块将把 env 标签设置为提供的 replacement，所以{env="production"} 将被添加到标签集：

1
2
3

- action: replace
  replacement: production
  target_label: env

当你把它和其他字段结合起来时，replace动作是最有用的。

下面是另一个例子：

- action: replace
  source_labels: [__meta_kubernetes_pod_name,__meta_kubernetes_pod_container_port_number]
  separator: ":"
  target_label: address

上面的片段将连接存储 __meta_kubernetes_pod_name 和__meta_kubernetes_pod_container_port_number的值。然后，提取的字符串将被设置为写入target_label，最终结果是{address="podname:8080}。

hashmod（哈希取模）

hashmod 动作提供了一个横向扩展 Prometheus 的机制。

重新标记的步骤是计算连接的标签值的 MD5 哈希值，对一个正整数 N 进行取模，结果是一个范围为 [0, N-1] 的数字。

一个例子可能会使这一点更清楚。请看下面的度量和重新标记步骤：

my_custom_metric{name="node",val="42"} 100

- action: hashmod
  source_labels: [name, val]
  separator: "-"
  modulus: 8
  target_label: __tmp_hashmod

连接的结果是字符串 “node-42”，字符串模数 8 的 MD5 是5。

$ python3
>>> import hashlib
>>> m = hashlib.md5(b"node-42")
>>> int(m.hexdigest(), 16) % 8
5

所以最终 {__tmp=5} 会被附加到指标的标签集上。

这最常用于将多个目标分散到 Prometheus 实例的集群中。下面的规则可以用来在 8 个 Prometheus 实例之间分配负载，每个实例负责刮取最终在 [0, 7] 范围内产生某个值的目标子集，而忽略其他所有目标。

1
2
3

- action: keep
  source_labels: [__tmp_hashmod]
  regex: 5

labelmap（标签映射）

labelmap 动作用于将一个或多个标签对映射到不同的标签名称。

任何标签对的名称与所提供的搜索结果相匹配的，将被复制到 replacement 字段中的新标签名称中，利用组引用（${1}，${2}，等等）。

replacement字段默认为只有$1，即第一个捕获的 relabel，所以它有时会被省略。

这里有一个例子。如果我们使用 Prometheus 的 Kubernetes SD，我们的目标将暂时暴露一些标签，如：

    __meta_kubernetes_node_name: 节点对象的名称。
    __meta_kubernetes_node_provider_id: 节点对象的云提供商的名称。
    __meta_kubernetes_node_address_<address_type>: 每个节点地址类型的第一个地址，如果它存在的话。
…
    __meta_kubernetes_namespace: 服务对象的命名空间。
    __meta_kubernetes_service_external_name: 服务的 DNS 名称。（适用于 ExternalName 类型的服务）。
    __meta_kubernetes_service_name: 服务对象的名称。
    __meta_kubernetes_service_port_name: 目标的服务端口的名称。
…
    __meta_kubernetes_pod_name: Pod 对象的名称。
    __meta_kubernetes_pod_ip: Pod 对象的 IP。
    __meta_kubernetes_pod_container_init: 如果该容器是一个 InitContainer，则为 true。
    __meta_kubernetes_pod_container_name: 目标地址指向的容器的名称。
…

以双下划线开头的标签在应用重新标注步骤后会被普罗米修斯删除，所以我们可以使用 labelmap 通过将它们映射到不同的名称来保留它们。

1
2
3

- action: labelmap
  regex: "__meta_kubernetes_(.*)"
  replacement: "k8s_${1}"

Prometheus 中重新标记的常见用例

下面是一个关于重新标记的常见用例的小清单，以及在什么地方适合添加重新标记的步骤：

当你想忽略一个子集的应用程序时；使用relabel_config
当在多个 Prometheus 服务器之间分割目标时；使用relabel_config + hashmod
当你想忽略一个高 cardinality 度量的子集时；使用metric_relabel_config
当向不同的端点发送不同的度量时；使用write_relabel_config

Learn more

今天就到此为止吧！希望你学到了一两件关于重标规则的事情，并且你在使用它们时更加得心应手。欲了解更多信息，请查看我们的文档，并在 Prometheus 文档中阅读更多信息。