From a260f2eb732ab1e1f05d4da41e0cda72febf276d Mon Sep 17 00:00:00 2001 From: Rossi Sun Date: Sun, 26 Jul 2026 16:13:04 -0700 Subject: [PATCH 1/2] tiup: document Prometheus external labels in Chinese --- .../customized-montior-in-tiup-environment.md | 22 +++++++++++++++++++ tiup/tiup-cluster-topology-reference.md | 4 ++++ tiup/tiup-dm-topology-reference.md | 4 ++++ 3 files changed, 30 insertions(+) diff --git a/tiup/customized-montior-in-tiup-environment.md b/tiup/customized-montior-in-tiup-environment.md index 1400df6f930f..1269ca83759f 100644 --- a/tiup/customized-montior-in-tiup-environment.md +++ b/tiup/customized-montior-in-tiup-environment.md @@ -72,6 +72,28 @@ monitoring_servers: 上述配置后，在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 additional_scrape_conf 字段的内容会添加到 Prometheus 配置文件的对应参数中。 +### 自定义 Prometheus external labels + +从 TiUP v1.17.0 开始，你可以在拓扑文件中配置 Prometheus 全局 `external_labels`。 + +1. 打开 TiDB 集群的拓扑配置文件 topology.yaml。 + +2. 在 monitoring_servers 的配置部分添加 `external_labels` 字段。 + + 以下为 topology.yaml 文件中的 monitoring_servers 配置示例： + + ```yaml + monitoring_servers: + - host: xxxxxxx + external_labels: + environment: production + region: us-east-1 + ``` + +3. 不要配置保留 label `cluster` 和 `monitor`，也不要使用以 `__` 开头的 label 名；所有 label 名都必须符合 Prometheus label name 规则。 + +上述配置后，在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 `external_labels` 字段渲染到 Prometheus 全局 `external_labels` 配置中。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败。 + ## 自定义 Grafana 配置 目前，TiUP 支持自定义 Grafana Dashboard 和其他配置。 diff --git a/tiup/tiup-cluster-topology-reference.md b/tiup/tiup-cluster-topology-reference.md index e003aa6f3be3..fb6ea5c5d7b0 100644 --- a/tiup/tiup-cluster-topology-reference.md +++ b/tiup/tiup-cluster-topology-reference.md @@ -535,6 +535,7 @@ scheduling_servers: - `arch`：`host` 字段所指定的机器的架构，若不指定该字段，则默认为 `global` 中的 `arch` - `resource_control`：针对该服务的资源控制，如果配置了该字段，会将该字段和 `global` 中的 `resource_control` 内容合并（若字段重叠，以本字段内容为准），然后生成 systemd 配置文件并下发到 `host` 指定机器。`resource_control` 的配置规则同 `global` 中的 `resource_control` - `additional_args`：从 TiUP v1.15.0 开始引入，用于配置 Prometheus 额外运行参数。该字段是一个数组，数组元素为 Prometheus 运行参数。例如，要开启 Prometheus 热加载功能，可以将该字段配置为 `--web.enable-lifecycle` +- `external_labels`：从 TiUP v1.17.0 开始引入，用于为 Prometheus 配置全局 `external_labels`，字段值为 key/value 对。可用于为 Prometheus `remote_write`、联邦抓取和告警附加稳定元数据。TiUP 会自动管理 `cluster` 和 `monitor` 这两个保留 label，因此不要在该字段中配置它们。以 `__` 开头的 label 名同样保留不可用，且所有 label 名都必须符合 Prometheus label name 规则。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败 - `additional_scrape_conf`：自定义 Prometheus scrape 配置。在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 `additional_scrape_conf` 字段的内容添加到 Prometheus 配置文件的对应参数中。更多信息，请参考[自定义监控组件的配置](/tiup/customized-montior-in-tiup-environment.md#自定义-prometheus-scrape-配置) 以上所有字段中，部分字段部署完成之后不能再修改。如下所示： @@ -555,6 +556,9 @@ monitoring_servers: rule_dir: /local/rule/dir additional_args: - --web.enable-lifecycle + external_labels: + environment: production + region: us-east-1 remote_config: remote_write: - queue_config: diff --git a/tiup/tiup-dm-topology-reference.md b/tiup/tiup-dm-topology-reference.md index 99b05d4f3395..3852e7db16fe 100644 --- a/tiup/tiup-dm-topology-reference.md +++ b/tiup/tiup-dm-topology-reference.md @@ -199,6 +199,7 @@ worker_servers: - `remote_write`：参考 Prometheus [``](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) 文档 - `remote_read`：参考 Prometheus [``](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read) 文档 - `external_alertmanagers`：若配置了 `external_alertmanagers`，Prometheus 会将配置行为报警通知到集群外的 Alertmanager。该字段为一个数组，数组的元素为每个外部的 Alertmanager，由 `host` 和 `web_port` 字段构成 +- `external_labels`：从 TiUP v1.17.0 开始引入，用于为 Prometheus 配置全局 `external_labels`，字段值为 key/value 对。可用于为 Prometheus `remote_write`、联邦抓取和告警附加稳定元数据。TiUP 会自动管理 `cluster` 和 `monitor` 这两个保留 label，因此不要在该字段中配置它们。以 `__` 开头的 label 名同样保留不可用，且所有 label 名都必须符合 Prometheus label name 规则。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败 - `os`：`host` 字段所指定的机器的操作系统，若不指定该字段，则默认为 `global` 中的 `os` - `arch`：`host` 字段所指定的机器的架构，若不指定该字段，则默认为 `global` 中的 `arch` - `resource_control`：针对该服务的资源控制，如果配置了该字段，会将该字段和 `global` 中的 `resource_control` 内容合并（若字段重叠，以本字段内容为准），然后生成 systemd 配置文件并下发到 `host` 指定机器。`resource_control` 的配置规则同 `global` 中的 `resource_control` @@ -219,6 +220,9 @@ worker_servers: monitoring_servers: - host: 10.0.1.11 rule_dir: /local/rule/dir + external_labels: + environment: production + region: us-east-1 remote_config: remote_write: - queue_config: From 7ddea36173afcbd3bdbd0c27cefc3f1aa48a5e44 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Mon, 27 Jul 2026 11:54:28 +0800 Subject: [PATCH 2/2] Refine wording and format --- tiup/customized-montior-in-tiup-environment.md | 14 ++++++++------ tiup/tiup-cluster-topology-reference.md | 2 +- tiup/tiup-dm-topology-reference.md | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/tiup/customized-montior-in-tiup-environment.md b/tiup/customized-montior-in-tiup-environment.md index 1269ca83759f..21893c00bf48 100644 --- a/tiup/customized-montior-in-tiup-environment.md +++ b/tiup/customized-montior-in-tiup-environment.md @@ -72,15 +72,15 @@ monitoring_servers: 上述配置后，在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 additional_scrape_conf 字段的内容会添加到 Prometheus 配置文件的对应参数中。 -### 自定义 Prometheus external labels +### 自定义 Prometheus 外部标签 从 TiUP v1.17.0 开始，你可以在拓扑文件中配置 Prometheus 全局 `external_labels`。 -1. 打开 TiDB 集群的拓扑配置文件 topology.yaml。 +1. 打开 TiDB 集群的拓扑配置文件 `topology.yaml`。 -2. 在 monitoring_servers 的配置部分添加 `external_labels` 字段。 +2. 在 `monitoring_servers` 的配置部分添加 `external_labels` 字段。 - 以下为 topology.yaml 文件中的 monitoring_servers 配置示例： + 以下为 `topology.yaml` 文件中的 `monitoring_servers` 配置示例： ```yaml monitoring_servers: @@ -90,9 +90,11 @@ monitoring_servers: region: us-east-1 ``` -3. 不要配置保留 label `cluster` 和 `monitor`，也不要使用以 `__` 开头的 label 名；所有 label 名都必须符合 Prometheus label name 规则。 +3. 不要配置保留 label `cluster` 和 `monitor`，也不要使用以 `__` 开头的 label 名；所有 label 名都必须符合 Prometheus 标签命名规则。 + +完成上述配置后，当你部署、扩容、缩容或重载 TiDB 集群时，TiUP 会将 `external_labels` 字段渲染到 Prometheus 全局 `external_labels` 配置中。 -上述配置后，在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 `external_labels` 字段渲染到 Prometheus 全局 `external_labels` 配置中。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败。 +如果使用不支持该字段的早期版本 TiUP 打开拓扑配置文件，TiUP 不会忽略该字段，而是会解析拓扑配置失败。 ## 自定义 Grafana 配置 diff --git a/tiup/tiup-cluster-topology-reference.md b/tiup/tiup-cluster-topology-reference.md index fb6ea5c5d7b0..1883351110a2 100644 --- a/tiup/tiup-cluster-topology-reference.md +++ b/tiup/tiup-cluster-topology-reference.md @@ -535,7 +535,7 @@ scheduling_servers: - `arch`：`host` 字段所指定的机器的架构，若不指定该字段，则默认为 `global` 中的 `arch` - `resource_control`：针对该服务的资源控制，如果配置了该字段，会将该字段和 `global` 中的 `resource_control` 内容合并（若字段重叠，以本字段内容为准），然后生成 systemd 配置文件并下发到 `host` 指定机器。`resource_control` 的配置规则同 `global` 中的 `resource_control` - `additional_args`：从 TiUP v1.15.0 开始引入，用于配置 Prometheus 额外运行参数。该字段是一个数组，数组元素为 Prometheus 运行参数。例如，要开启 Prometheus 热加载功能，可以将该字段配置为 `--web.enable-lifecycle` -- `external_labels`：从 TiUP v1.17.0 开始引入，用于为 Prometheus 配置全局 `external_labels`，字段值为 key/value 对。可用于为 Prometheus `remote_write`、联邦抓取和告警附加稳定元数据。TiUP 会自动管理 `cluster` 和 `monitor` 这两个保留 label，因此不要在该字段中配置它们。以 `__` 开头的 label 名同样保留不可用，且所有 label 名都必须符合 Prometheus label name 规则。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败 +- `external_labels`：从 TiUP v1.17.0 开始引入，该字段用于以键值对的形式配置 Prometheus 全局 `external_labels`。你可以使用该字段为 Prometheus 的 `remote_write`、联邦抓取 (federation) 和告警附加稳定元数据。TiUP 会自动管理并保留 `cluster` 和 `monitor` 标签，因此不要在该字段中配置这些标签。此外，以 `__` 开头的标签名称同样是保留的，所有标签名称都必须符合 Prometheus 标签命名规则。如果使用不支持该字段的早期版本 TiUP 读取拓扑配置文件，TiUP 不会忽略该字段，而是直接解析失败。 - `additional_scrape_conf`：自定义 Prometheus scrape 配置。在集群进行 deploy/scale-out/scale-in/reload 操作时，TiUP 会将 `additional_scrape_conf` 字段的内容添加到 Prometheus 配置文件的对应参数中。更多信息，请参考[自定义监控组件的配置](/tiup/customized-montior-in-tiup-environment.md#自定义-prometheus-scrape-配置) 以上所有字段中，部分字段部署完成之后不能再修改。如下所示： diff --git a/tiup/tiup-dm-topology-reference.md b/tiup/tiup-dm-topology-reference.md index 3852e7db16fe..a87b8a3f7e2e 100644 --- a/tiup/tiup-dm-topology-reference.md +++ b/tiup/tiup-dm-topology-reference.md @@ -199,7 +199,7 @@ worker_servers: - `remote_write`：参考 Prometheus [``](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) 文档 - `remote_read`：参考 Prometheus [``](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read) 文档 - `external_alertmanagers`：若配置了 `external_alertmanagers`，Prometheus 会将配置行为报警通知到集群外的 Alertmanager。该字段为一个数组，数组的元素为每个外部的 Alertmanager，由 `host` 和 `web_port` 字段构成 -- `external_labels`：从 TiUP v1.17.0 开始引入，用于为 Prometheus 配置全局 `external_labels`，字段值为 key/value 对。可用于为 Prometheus `remote_write`、联邦抓取和告警附加稳定元数据。TiUP 会自动管理 `cluster` 和 `monitor` 这两个保留 label，因此不要在该字段中配置它们。以 `__` 开头的 label 名同样保留不可用，且所有 label 名都必须符合 Prometheus label name 规则。若使用不支持该字段的旧版 TiUP 打开包含该字段的拓扑文件，不会忽略未知字段，而是直接解析失败 +- `external_labels`：从 TiUP v1.17.0 开始引入，该字段用于以键值对的形式配置 Prometheus 全局 `external_labels`。你可以使用该字段为 Prometheus 的 `remote_write`、联邦抓取 (federation) 和告警附加稳定元数据。TiUP 会自动管理并保留 `cluster` 和 `monitor` 标签，因此不要在该字段中配置这些标签。此外，以 `__` 开头的标签名称同样是保留的，所有标签名称都必须符合 Prometheus 标签命名规则。如果使用不支持该字段的早期版本 TiUP 读取拓扑配置文件，TiUP 不会忽略该字段，而是直接解析失败。 - `os`：`host` 字段所指定的机器的操作系统，若不指定该字段，则默认为 `global` 中的 `os` - `arch`：`host` 字段所指定的机器的架构，若不指定该字段，则默认为 `global` 中的 `arch` - `resource_control`：针对该服务的资源控制，如果配置了该字段，会将该字段和 `global` 中的 `resource_control` 内容合并（若字段重叠，以本字段内容为准），然后生成 systemd 配置文件并下发到 `host` 指定机器。`resource_control` 的配置规则同 `global` 中的 `resource_control`