标签 · XB 现场笔记

Kubernetes 标签定义选择关系，不代替授权

Thu, 09 Sep 2027 00:00:00 +0000

标签是 Kubernetes 用于选择对象的键值元数据。Service 选择器、运维查询和工作负载控制器都可能依赖标签，但每个消费者有自己的 API 和处理方式。因此，标签变化可能改变对象所属集合，同时底层进程仍然健康。审阅时应把标签视为真实消费者的输入，而不是仅用于展示的贴纸，否则看似简单的文字修改也可能改变路由。

确认正在使用哪一种选择语言

标签键采用限定名称格式，值也有字符和长度约束。标签值可以为空；不为空时，其允许字符及首尾位置受到限制，最大长度为六十三个字符。任意长段落或不受约束的 JSON 并不适合放在标签值里。描述性信息可以采用 annotation，但仍然要遵守对应格式和消费契约，不能把换字段当成取消所有限制。

等值条件检查某个键是否具有指定值，集合条件还支持成员关系与存在性检查。同一个选择器里的多个条件需要同时满足。有一个容易忽略的细节：track!=canary 也会匹配根本没有 track 键的对象。如果不允许键缺失，应另外要求这个键存在，不能认为“不等于某值”就已经隐含“这个键肯定存在”。

不同资源的选择字段结构并不相同。普通带选择器的 Service 使用等值映射，不能把完整集合表达式随意塞进某个映射值。另一些 API 提供 LabelSelector 结构，而 kubectl 列表查询能够接受选择表达式。把命令行中方便使用的查询转换成清单之前，应核对目标字段的真实结构，避免把同一个概念误当成完全相同的输入格式。

坏掉的样子

Service 选择器会识别本命名空间中匹配的 Pod，端点机制再跟踪地址与就绪状态。标签匹配本身不证明服务已经准备好，也不证明端口配置正确。在普通就绪策略下，路由可用目标还取决于端点条件。检查时应查看相应 EndpointSlice 和应用探测结果，不能在一次标签查询成功后就停止验证。

publishNotReadyAddresses 设置会改变服务发现对就绪状态的处理。在这种配置下，不能仅凭端点被标成就绪，就断言对应容器已经通过应用探测。下面实验采用普通默认行为，没有测试这个覆盖设置，因此结果也不应无条件推广到使用该选项的服务。

给健康 Pod 修改标签，可能把它移出 Service，却并不终止进程。过宽的条件则可能把原本不该提供服务的工作负载加入后端。如果 Pod 由控制器管理，手工改标签还可能影响所属关系与协调行为。应通过负责的控制器更新预期状态，并在改变共享键含义之前核对主要消费者，避免修好一个查询却破坏另一条路由。

选择器不是网络授权。某个 Pod 即使不属于一个 Service，也可能继续通过自身地址或其他 Service 被访问，除非另有控制阻止。NetworkPolicy、应用授权和路由分别解决不同部分，不能把选择器描述成能够拒绝所有未选中对象直连流量的访问名单。对象是否被发现，与请求最终是否允许，必须分别成立。

快速验证

以下实验及观察结果沿用原文记录。本次审阅没有重新执行 Kubernetes 集成实验；文中的成功结果属于历史记录，不代表本轮取得了新的运行证据。

准备可丢弃的 Kubernetes 集群，确保 kubectl 可用，节点已有 python:3.11-slim-bookworm 镜像。保存代码为 label-selectors.py，执行 python3 label-selectors.py KUBECONFIG_PATH CONTEXT，明确传入测试集群配置与上下文。脚本在独有命名空间创建三个独立 HTTP Pod 和一个 Service，结束后删除它们。实测服务端版本是 Kubernetes 1.34.11。

import json
import subprocess
import sys
import time
from uuid import uuid4

assert len(sys.argv) == 3, 'usage: python3 example.py DISPOSABLE_KUBECONFIG CONTEXT'
base = ['kubectl', '--kubeconfig', sys.argv[1], '--context', sys.argv[2], '--request-timeout=30s']
image = 'python:3.11-slim-bookworm'


def k(*args, payload=None, expected=0):
 result = subprocess.run(base + list(args), input=json.dumps(payload) if payload is not None else None,
 capture_output=True, text=True, timeout=150)
 if expected is not None:
 assert result.returncode == expected, result.stderr
 return result


def obj(namespace, kind, name=None, selector=None):
 args = ['get', kind, '-n', namespace, '-o', 'json']
 if name:
 args.append(name)
 if selector:
 args += ['-l', selector]
 return json.loads(k(*args).stdout)


def apply(namespace, data):
 return k('apply', '-n', namespace, '-f', '-', payload=data)


def wait_for(read, ready, seconds=120):
 until = time.monotonic() + seconds
 while time.monotonic() < until:
 value = read()
 if ready(value):
 return value
 time.sleep(0.5)
 raise AssertionError('expected Kubernetes condition did not arrive')


def pod_ready(pod):
 return any(c['type'] == 'Ready' and c['status'] == 'True'
 for c in pod.get('status', {}).get('conditions', []))


def spec(script='import time; time.sleep(600)'):
 return {'automountServiceAccountToken': False, 'terminationGracePeriodSeconds': 1,
 'containers': [{'name': 'app', 'image': image, 'imagePullPolicy': 'IfNotPresent',
 'command': ['python3', '-c', script],
 'resources': {'requests': {'cpu': '10m', 'memory': '24Mi'},
 'limits': {'cpu': '200m', 'memory': '96Mi'}}}]}

namespace = 'notes-labels-' + uuid4().hex[:8]
k('create', 'namespace', namespace)
try:
 for name, role, track in [('a', 'reader', 'stable'), ('b', 'reader', 'canary'), ('c', 'writer', None)]:
 script = '''from http.server import BaseHTTPRequestHandler,HTTPServer
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 data=LABEL.encode();self.send_response(200);self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data)
 def log_message(self,*args): pass
HTTPServer(('0.0.0.0',8080),Handler).serve_forever()
'''.replace('LABEL', repr(name))
 podspec = spec(script)
 podspec['containers'][0]['readinessProbe'] = {'httpGet': {'path': '/', 'port': 8080}, 'periodSeconds': 1}
 labels = {'app': 'catalog', 'role': role}
 if track:
 labels['track'] = track
 apply(namespace, {'apiVersion': 'v1', 'kind': 'Pod', 'metadata': {'name': name, 'labels': labels}, 'spec': podspec})
 for name in ('a', 'b', 'c'):
 wait_for(lambda name=name: obj(namespace, 'pod', name), pod_ready)
 apply(namespace, {'apiVersion': 'v1', 'kind': 'Service', 'metadata': {'name': 'readers'},
 'spec': {'selector': {'app': 'catalog', 'role': 'reader'}, 'ports': [{'port': 80, 'targetPort': 8080}]}})
 def selected():
 slices = obj(namespace, 'endpointslices', selector='kubernetes.io/service-name=readers')['items']
 return {e['targetRef']['name'] for item in slices for e in item.get('endpoints', [])
 if e.get('conditions', {}).get('ready') and e.get('targetRef')}
 before = wait_for(selected, lambda names: names == {'a', 'b'})
 inequality = {p['metadata']['name'] for p in obj(namespace, 'pods', selector='app=catalog,track!=canary')['items']}
 assert inequality == {'a', 'c'}
 expression = {p['metadata']['name'] for p in obj(namespace, 'pods', selector='app in (catalog),role=reader')['items']}
 assert expression == {'a', 'b'}
 writer_ip = obj(namespace, 'pod', 'c')['status']['podIP']
 probe = 'from urllib.request import urlopen; print(urlopen(' + repr('http://'+writer_ip+':8080/') + ',timeout=3).read().decode())'
 assert k('exec', '-n', namespace, 'a', '--', 'python3', '-c', probe).stdout.strip() == 'c'
 k('label', 'pod', 'b', '-n', namespace, 'role=writer', '--overwrite')
 after = wait_for(selected, lambda names: names == {'a'})
 assert pod_ready(obj(namespace, 'pod', 'b'))
 invalid = k('patch', 'pod', 'a', '-n', namespace, '--type=merge',
 '-p', json.dumps({'metadata': {'labels': {'notes.example/value': 'has spaces'}}}), expected=None)
 assert invalid.returncode != 0 and 'Invalid' in invalid.stderr
 print(json.dumps({'service_targets_before': sorted(before), 'service_targets_after': sorted(after),
 'inequality_also_matches_missing_key': sorted(inequality),
 'set_selector_matches': sorted(expression), 'excluded_pod_directly_reachable': True,
 'invalid_label_value_rejected': True}))
finally:
 k('delete', 'namespace', namespace, '--wait=true', '--timeout=90s')

Pod a 与 b 的 role 为 reader，c 为 writer；三者共享 app=catalog，并通过 HTTP 就绪探测。a 的 track 为 stable，b 为 canary，c 则没有这个键。reader Service 最初具有 a、b 两个就绪目标。集合式查询能够找到这两个 reader，而 track!=canary 会找到 a、c，实际确认缺少键时也会匹配不等式。

从 a 向 c 的 Pod 地址发起真实 HTTP 请求，会返回 c，即使 c 不属于 reader Service。随后把 b 的 role 改为 writer，Service 的就绪端点集合只剩 a，但 b 自己仍然处于就绪状态。另一个包含空格标签值的补丁被 API 拒绝。原文报告所有断言都已运行通过，结果同时覆盖查询、控制器维护的端点和实际网络请求。

实验验证了隔离测试网络中的 API 选择、EndpointSlice 变化和直连可达性，没有测试所有控制器的接管规则，没有执行网络策略隔离，也没有测量 Service 性能。审阅真实路由变化时，应分别观察选择意图、端点就绪和访问政策，使每一层都有可检查的结果，而不是靠某个标签名称推断完整安全边界。

来源

Kubernetes: Labels and Selectors，合法值、等值及集合式选择条件，已核验 2026-10-15。
Kubernetes: Services，基于选择器的后端发现，已核验 2026-10-15。
Kubernetes: EndpointSlices，端点身份及就绪条件，已核验 2026-10-15。

样本重新标记在入库前过滤指标

Wed, 04 Aug 2027 00:00:00 +0000

Prometheus 存在多个重新标记阶段，相似语法容易遮住不同作用。目标重新标记在采集之前处理发现目标，样本重新标记则在抓取之后、入库之前处理采集样本。前一个阶段的 drop 可以让某个端点不被抓取，后一个阶段的相同动作则从已经获取的响应中丢弃匹配样本。首先确定阶段，才能判断配置到底改变了哪一部分观测。

先决定删除数据，还是删除标签

在 metric_relabel_configs 中，action: drop 匹配组合后的源标签值，并丢弃匹配样本。使用 __name__ 作为输入时，可以拒绝指定指标族。它不是删除这个源标签却保留样本的意思。如果对一个广泛存在的值使用过宽条件，可能丢掉远超预期的数据，所以不能仅凭动作名称中有“删除”就认为它只影响元数据。

action: labeldrop 则把正则表达式用于标签名称，从保留样本中移除匹配标签；labelkeep 只保留名称匹配的标签。两者都不会求和或生成汇总。前一类操作删除观测，后一类操作改变身份，应该按照预期数据契约选择，而不是把名称相近的动作当成可互换参数。留下数值但删掉维度，也可能比直接过滤一部分样本带来更隐蔽的问题。

重新标记表达式默认在两端锚定。替换或过滤规则需要在对应阶段使用正确的源标签与模式。发现元数据通常属于目标阶段，到样本处理阶段时，已不能继续期待使用 __meta_ 输入。需要保留的上下文应提前复制到普通目标标签，而不是假定每个导出指标都会携带内部发现字段。配置语法相同，不代表输入集合也相同。

删除维度之后仍须保持唯一身份

时间序列由指标名和完整标签集合识别。移除区分两条观测的标签，可能让它们身份重叠，产生重复样本冲突或丢失区别。Prometheus 不会自动推断这些数值该求和、取平均还是任选其一。如果真正需要服务总量，应优先采用受控维度的仪表化以及明确查询聚合，而不是把标签删除当成自动汇总机制。

本例只在剩余路由身份本来就唯一的情况下删除构建标签，这是受控前提，不表示可以从任意导出器移除任何昂贵标签。上线前应使用有代表性的输出检查碰撞，也应核对引用被删标签的面板和告警。抓取成功只能说明采集过程完成，不能保证这些消费者仍会选择正确数据，更不能保证历史与新数据可以直接比较。

坏掉的样子

把样本过滤规则放进目标重新标记中，可能移除整个端点，而不是一类昂贵指标。反过来，样本过滤也不会阻止导出器生成响应，或阻止响应字节经过网络。它减少的是入库保留的样本。如果昂贵部分在采集本身，还需要处理仪表化或导出器行为，不能把存储侧过滤描述为同时消除了全部上游成本。

up 等自动生成的抓取序列不经过样本重新标记，因此在这个阶段尝试删除 up，不会隐藏系统生成的指标。健康的 up 可以与被主动丢弃的业务指标同时存在，解释数据缺失时应结合过滤配置。修改规则影响未来入库，不会重写已经保存的历史标签，所以查询跨越变更时刻时也可能看到两种身份。

应把 scrape_samples_post_metric_relabeling 与目标错误、up 一起观察。配置的样本数量上限在样本重新标记之后生效，超出时会让抓取失败，并不是任意保留前面一部分额度内样本。因此，主动过滤与入库上限失败需要不同诊断，即便二者都表现为预期业务序列缺失。

快速验证

保存为 metric-relabel.py 后执行 python3 metric-relabel.py。需要 Docker 与 Prometheus 3.5.1，必要时由 Docker 获取镜像。同一个静态文本端点分别被原始任务与过滤任务抓取。路径使用 .txt 以提供文本内容类型，启动过程等待真正出现样本，不假定服务刚启动时目标列表已经填充完成。

import http.client
import io
import json
import subprocess
import time
import uuid
from urllib.parse import quote

name = "xbcatm-monitoring-" + uuid.uuid4().hex[:12]


class ResponseSocket:
 def __init__(self, data):
 self.data = data

 def makefile(self, mode):
 return io.BytesIO(self.data)


def request(method, path, body="", content_type="application/json"):
 body = body.encode()
 headers = (f"{method} {path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\n"
 f"Connection: close\r\nContent-Type: {content_type}\r\n"
 f"Content-Length: {len(body)}\r\n\r\n").encode()
 result = subprocess.run(
 ["docker", "exec", "-i", name, "/bin/nc", "-w", "3", "127.0.0.1", str(port)],
 input=headers + body, capture_output=True, timeout=5,
 )
 if result.returncode:
 raise RuntimeError(result.stderr.decode())
 response = http.client.HTTPResponse(ResponseSocket(result.stdout))
 response.begin()
 return response.status, response.read().decode()


def get_json(path):
 status, body = request("GET", path)
 assert status == 200, (status, body)
 return json.loads(body)


def eventually(check):
 for attempt in range(150):
 try:
 value = check()
 if value:
 return value
 except (RuntimeError, AssertionError, http.client.HTTPException):
 pass
 time.sleep(0.1)
 raise AssertionError("Expected local server state did not appear")


def query(expression):
 response = get_json("/api/v1/query?query=" + quote(expression, safe=""))
 assert response["status"] == "success"
 return response["data"]["result"]


def value(expression):
 result = query(expression)
 assert len(result) == 1, (expression, result)
 return float(result[0]["value"][1])

port = 9090
# Requires Docker and the Prometheus 3.5.1 image.
script = r"""set -eu
mkdir -p /tmp/www /tmp/targets
cat > /tmp/prom.yml <<'PROM_CONFIG'
global:
 scrape_interval: 1s
 scrape_timeout: 500ms
scrape_configs:
 - job_name: raw
 metrics_path: /metrics.txt
 static_configs:
 - targets: ['127.0.0.1:8080']
 - job_name: filtered
 metrics_path: /metrics.txt
 static_configs:
 - targets: ['127.0.0.1:8080']
 metric_relabel_configs:
 - source_labels: [__name__]
 regex: 'debug_.+|up'
 action: drop
 - regex: build_sha
 action: labeldrop

PROM_CONFIG
cat > /tmp/www/metrics.txt <<'METRIC_DATA'
# TYPE demo_requests_total counter
demo_requests_total{route="/orders",build_sha="release-a"} 42
# TYPE debug_alloc_bytes gauge
debug_alloc_bytes{kind="scratch"} 9

METRIC_DATA
/bin/httpd -f -p 127.0.0.1:8080 -h /tmp/www > /tmp/httpd.log 2>&1 &
exec /bin/prometheus --config.file=/tmp/prom.yml --storage.tsdb.path=/tmp/data --web.listen-address=127.0.0.1:9090
"""
try:
 subprocess.run(
 ["docker", "run", "-d", "--rm", "--name", name, "--network", "none",
 "--entrypoint", "/bin/sh", "prom/prometheus:v3.5.1", "-c", script],
 check=True, capture_output=True, text=True, timeout=20,
 )
 eventually(lambda: len(query('demo_requests_total')) == 2)
 raw = query('demo_requests_total{job="raw"}')[0]
 filtered = query('demo_requests_total{job="filtered"}')[0]
 assert raw["metric"]["build_sha"] == "release-a"
 assert "build_sha" not in filtered["metric"]
 assert float(raw["value"][1]) == float(filtered["value"][1]) == 42
 assert len(query('debug_alloc_bytes{job="raw"}')) == 1
 assert query('debug_alloc_bytes{job="filtered"}') == []
 assert value('up{job="filtered"}') == 1
 print(json.dumps({"raw_labels": raw["metric"], "filtered_labels": filtered["metric"],
 "debug_series_dropped": True, "generated_up_preserved": True}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

原始请求序列保留 build_sha="release-a"，过滤后的序列移除该标签，但保留路由与数值四十二。调试指标存在于原始任务，在过滤任务中消失。虽然 drop 模式也写了 up，过滤任务自动生成的 up 仍为一。断言通过真实查询接口逐项核对这些差异，分别证明样本被过滤、标签被删除以及自动生成序列的例外。

两个任务具有不同的任务标签，本实验在删除标签后也没有竞争的请求序列。因此，它验证阶段语义，不证明任意迁移都不会发生身份碰撞。所有流量留在容器回环地址，不挂载宿主机目录，也不发布端口，结束时仅清理实验容器。将相同策略用于生产前，仍应验证真实导出器身份与受影响消费者。

来源

Prometheus：任务与实例，抓取结果与保留样本计数，已核验 2026-10-15。
Prometheus: configuration，样本重新标记、样本过滤、标签删除与自动生成序列的例外，已核验 2026-09-13。
Prometheus: data model，指标名与完整标签集合定义序列身份，已核验 2026-09-13。
Prometheus: HTTP API，查询保留的指标标签与数值，已核验 2026-09-13。

外部标签标识 Prometheus 对外发送的数据

Wed, 09 Jun 2027 00:00:00 +0000

多个 Prometheus 向同一系统提供数据时，下游需要知道信息来自哪个采集器或环境。全局 external_labels 可以在与外部系统通信时补充这些上下文。但它不会重写每条本地存储序列，也不会覆盖对外序列中已经存在的同名标签。理解这两条边界，才能避免用错误的查询位置判断配置是否生效，也能避免误以为全局值一定压过目标值。

本地存储与对外身份并不相同

本地查询 up 通常看到抓取和重新标记产生的标签，外部标签 prom_region 并不一定出现。它没有出现在本地查询中，不能证明配置失败。应将适当的对外接口与本地结果比较；联邦接口提供了一种直接观察差异的方法，无需为了验证这个行为先接入远端存储系统。检查位置必须与希望验证的机制对应。

配置契约也涉及远端存储和告警等外部通信，但各条下游路径还可能有自己的重新标记与处理步骤。验证某条路径时，需要观察它实际到达的消费者。本地评估的记录规则不会因为保存了一条新序列，就自动获得所有外部标签。外部标签在相关通信边界补充，不是统一改写所有本地查询结果的机制。

序列已有的标签优先

如果目标序列已经具有 cluster="target-cluster"，全局外部标签配置为 cluster="collector-cluster"，不会把目标值替换掉。外部标签补充的是缺少的标签名称。这是已定义的行为，不能编造成新版本遇到冲突必定拒绝或记录错误。因此，本地指标对外导出时保留的集群值，可能不同于操作人员以为全局配置会强制设置的值。

需要区分目标身份与采集器身份时，应约定独立的采集器标签名，并检查导出器和重新标记规则是否与之冲突。联邦场景中，目标端的 honor_labels 还决定如何处理源标签与本端抓取标签的冲突。这个接收端行为，与源端如何向联邦响应补充外部标签是两件事，不能因为一侧正确便跳过另一侧检查。

稳定标签不会自动实现去重

改变全局标签值，会改变之后导出序列的身份。已经保存在下游的历史仍在旧标签下，不会被重写。修改选择器和面板时，应考虑这条历史边界。添加很多标签也不必然有益：固定标签提供上下文，不同采集器的不同取值则增加消费者需要处理的身份区别，应根据实际查询需求决定，而不是把能写的字段都写进去。

两个采集器抓取相同目标时，可能在不同副本标签下导出重复观测。直接跨副本求和，会让流量看起来翻倍。外部标签让这些副本可以被区分，却不会替下游配置高可用去重。标签也不是租户授权边界；如果存在隔离要求，应核对存储系统真实的权限和查询行为，不能仅依赖名称看起来来自不同环境。

告警重新标记发生在补充外部标签之后。因此，高可用采集器可以在发送等价告警前仅去掉副本区分字段，同时为需要它的存储链路保留该指标标签。仍须核对最终告警标签确实等价，不能把真正区分责任或环境的字段也删掉。度量副本去重与告警身份归一化属于不同路径，需要分别验收。

坏掉的样子

团队可能在本地查询中寻找外部标签，找不到便反复修改本来有效的配置。相反，也可能看到联邦输出带有预期标签，就认为远端写入和告警路由都已验证。应检查具体路径和最终标签，包括下游重新标记的影响，而不是把一个接口的结果当成全部集成已经成功的证据。目标标签与全局值相同的测试，还会掩盖真正的冲突优先级。

快速验证

保存为 external-labels.py 后执行 python3 external-labels.py。实验需要 Docker 与 Prometheus 3.5.1 镜像，未缓存时可能由 Docker 下载。单个一次性 Prometheus 抓取自己，随后比较本地查询响应与文本格式的联邦输出。所有 HTTP 请求都停留在容器回环地址，不发布宿主机端口，也没有外部网络访问。

import json
import re
import subprocess
import uuid

# Requires Docker and the public Prometheus 3.5.1 image.
# All HTTP traffic stays on loopback inside one disposable container.
script = r"""set -eu
cat > /tmp/prom.yml <<'CONFIG'
global:
 scrape_interval: 1s
 scrape_timeout: 500ms
 external_labels:
 cluster: collector-cluster
 prom_region: lab-region
 replica: one
scrape_configs:
 - job_name: self
 static_configs:
 - targets: ['127.0.0.1:9090']
 labels:
 cluster: target-cluster
CONFIG
/bin/prometheus --config.file=/tmp/prom.yml --storage.tsdb.path=/tmp/data \
 --web.listen-address=127.0.0.1:9090 > /tmp/prom.log 2>&1 &
for attempt in $(seq 1 30); do
 if wget -qO /tmp/ready.json 'http://127.0.0.1:9090/api/v1/query?query=up%20%3D%3D%201'; then
 if grep -q '"status":"success"' /tmp/ready.json && ! grep -q '"result":\[\]' /tmp/ready.json; then
 wget -qO /tmp/local.json 'http://127.0.0.1:9090/api/v1/query?query=up'
 wget -qO /tmp/federated.txt --header='Accept: text/plain; version=0.0.4' \
 'http://127.0.0.1:9090/federate?match%5B%5D=up'
 cat /tmp/local.json
 printf '\n'
 cat /tmp/federated.txt
 exit 0
 fi
 fi
 sleep 1
done
cat /tmp/prom.log >&2
exit 1
"""
name = "xbcatm-prom-live-" + uuid.uuid4().hex[:12]
try:
 result = subprocess.run(
 ["docker", "run", "--rm", "--name", name, "--network", "none", "-i",
 "--entrypoint", "/bin/sh", "prom/prometheus:v3.5.1", "-s"],
 input=script, text=True, capture_output=True, timeout=45,
 )
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
if result.returncode:
 raise RuntimeError(result.stderr or result.stdout)
local_json, _, exported = result.stdout.partition("\n")
payload = json.loads(local_json)
assert payload["status"] == "success"
local = next(a["metric"] for a in payload["data"]["result"]
 if a["metric"]["job"] == "self")
line = next(line for line in exported.splitlines() if line.startswith("up{"))
# The fixture's controlled label values contain no quotes or escape sequences.
outbound = dict(re.findall(r'(\w+)="([^"]*)"', line))
assert outbound["prom_region"] == "lab-region" and outbound["replica"] == "one"
assert outbound["cluster"] == local["cluster"] == "target-cluster"
assert "prom_region" not in local and "replica" not in local
print(json.dumps({"federated_labels": outbound, "local_labels": local}, indent=2))

本地标签包含 cluster="target-cluster"，但没有 prom_region 和 replica。联邦输出补入 prom_region="lab-region" 与 replica="one"，同时保留原有集群值。程序对这三个事实分别断言。解析器仅处理本实验中不含引号和转义序列的受控标签值，不是能够解析任意指标响应的通用组件，不能直接拿去处理未知导出内容。

退出时仅清理本次唯一名称的容器。结果证明源端联邦行为及本地与对外的区别，没有验证联邦接收端、远端写入接收器、高可用去重或通知送达。这些集成检查仍须观察各自的下游接口和实际配置，才能获得对应路径的完成证据。

来源

Prometheus: configuration，外部标签在对外通信时补充缺少的标签，已核验 2026-10-15。
Prometheus: federation，联邦选择器与保留上游标签，已核验 2026-10-15。
Prometheus: HTTP API，用于对照的本地查询结果，已核验 2026-10-15。

目标重新标记在抓取前选择目标并整理标签

Tue, 06 Apr 2027 00:00:00 +0000

服务发现产生候选目标及其元数据，目标重新标记在 Prometheus 抓取之前处理这些候选项。它可以保留或过滤目标、改变访问地址，并创建随采集序列一起保存的标签。这与改写单个抓取样本发生在不同阶段。先弄清操作阶段，才能避免本来只想去掉一个指标，却因为配置位置错误而把整个目标从采集范围中移除。

定义规则前先查看发现输入

发现结果包含 __address__ 等内部标签，以及由具体发现机制提供的 __meta_ 字段。文件发现中的 __meta_filepath 指明目标来自哪个文件。这些元数据在目标重新标记期间可以使用，但内部标签会在该阶段结束后从最终目标标签集中移除。如果后续查询需要某个值，应明确把它复制到普通标签中，不能假定所有发现信息都会自动入库。

准确的元数据名称取决于发现机制。从 Kubernetes 发现配置复制过来的规则，不会自动适用于文件发现。组合输入时，缺少的源标签贡献空值，因此依赖一个不存在字段的保留规则，可能过滤所有候选项。排查网络故障之前，应通过目标接口或发现视图检查实际输入标签，先确认目标是否真的进入了抓取阶段。

规则顺序决定最终身份

重新标记步骤按照配置顺序执行。keep 动作仅保留组合源标签值匹配正则表达式的目标，drop 动作则移除匹配目标。正则表达式默认在两端锚定。replace 动作可以把捕获的文本复制到目标标签，而新值又能成为同一序列中后续规则的输入。因此，互换两个步骤可能改变结果，即使每条规则本身都能够通过解析。

复制一个值并不会自动删除原标签。确实需要删除时，它是另一项操作，而且不能破坏抓取或消费者依赖的身份信息。修改 __address__ 会改变 Prometheus 实际访问的端点，修改普通标签则改变上下文。两者都不能简单描述成给面板字段换一个好看的名字：地址变化可能影响可达性，标签变化则可能影响路由、聚合和历史查询。

目标标签能够影响从该目标收集的所有序列。应选择服务或有意义的部署范围等稳定字段，而不是复制全部发现注解。频繁变化的构建标识，可能让大量指标同时产生新身份。因此，发现配置中的一个小改动，能够影响远大于配置文件自身规模的存储数据及其消费者，需要根据真实查询需求审阅。

坏掉的样子

被重新标记过滤的目标，不是一个 up=0 的已配置目标。它没有被抓取，失败抓取查询可能永远不会报告它。预期服务消失时，应对照发现候选项、被过滤目标与活动目标。若告警假定全部预期成员始终存在对应 up 序列，一条错误保留规则就可能让整组目标看起来像安静且健康的空集合。

复制错误元数据也可能得到外观合理、语义却错误的归属标签。查询结果很整齐，不代表数据真的属于被标注的服务。应一起审阅执行顺序、捕获组和最终标签。大范围删除标签还可能合并原本不同的身份，目标重新标记不会为了补偿信息损失而自动计算聚合值，不能把去标签当成汇总方法。

如果没有规则设置 instance，Prometheus 会使用最终的 __address__ 作为默认值，因此改写地址可能同时改变访问端点与默认身份。还应检查 honor_labels：目标导出标签与抓取侧标签冲突时，结果由这个配置决定，不能笼统认为目标标签一定覆盖导出器提交的所有同名值。

快速验证

把程序保存为 target-relabel.py，执行 python3 target-relabel.py。需要 Docker 和 Prometheus 3.5.1，镜像未缓存时可能下载。隔离容器内同时提供静态文本指标端点与文件发现清单，清单包含一个接口目标和一个应被过滤的目标。指标路径使用 /metrics.txt，使 HTTP 响应具有 Prometheus 接受的文本内容类型，避免端点格式问题遮住标签实验。

import http.client
import io
import json
import subprocess
import time
import uuid
from urllib.parse import quote

name = "xbcatm-monitoring-" + uuid.uuid4().hex[:12]


class ResponseSocket:
 def __init__(self, data):
 self.data = data

 def makefile(self, mode):
 return io.BytesIO(self.data)


def request(method, path, body="", content_type="application/json"):
 body = body.encode()
 headers = (f"{method} {path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\n"
 f"Connection: close\r\nContent-Type: {content_type}\r\n"
 f"Content-Length: {len(body)}\r\n\r\n").encode()
 result = subprocess.run(
 ["docker", "exec", "-i", name, "/bin/nc", "-w", "3", "127.0.0.1", str(port)],
 input=headers + body, capture_output=True, timeout=5,
 )
 if result.returncode:
 raise RuntimeError(result.stderr.decode())
 response = http.client.HTTPResponse(ResponseSocket(result.stdout))
 response.begin()
 return response.status, response.read().decode()


def get_json(path):
 status, body = request("GET", path)
 assert status == 200, (status, body)
 return json.loads(body)


def eventually(check):
 for attempt in range(150):
 try:
 value = check()
 if value:
 return value
 except (RuntimeError, AssertionError, http.client.HTTPException):
 pass
 time.sleep(0.1)
 raise AssertionError("Expected local server state did not appear")


def query(expression):
 response = get_json("/api/v1/query?query=" + quote(expression, safe=""))
 assert response["status"] == "success"
 return response["data"]["result"]


def value(expression):
 result = query(expression)
 assert len(result) == 1, (expression, result)
 return float(result[0]["value"][1])

port = 9090
# Requires Docker and the Prometheus 3.5.1 image.
script = r"""set -eu
mkdir -p /tmp/www /tmp/targets
cat > /tmp/prom.yml <<'PROM_CONFIG'
global:
 scrape_interval: 1s
 scrape_timeout: 500ms
scrape_configs:
 - job_name: discovered
 metrics_path: /metrics.txt
 file_sd_configs:
 - files: ['/tmp/targets/*.json']
 relabel_configs:
 - source_labels: [role]
 regex: api
 action: keep
 - source_labels: [__meta_filepath]
 regex: '.*/([^/]+)[.]json'
 target_label: discovery_file
 replacement: '$1'

PROM_CONFIG
cat > /tmp/www/metrics.txt <<'METRIC_DATA'
# TYPE demo_requests_total counter
demo_requests_total{route="/orders",build_sha="release-a"} 42
# TYPE debug_alloc_bytes gauge
debug_alloc_bytes{kind="scratch"} 9

METRIC_DATA
cat > /tmp/targets/lab.json <<'TARGETS'
[{"targets": ["127.0.0.1:8080"], "labels": {"role": "api"}}, {"targets": ["127.0.0.1:1"], "labels": {"role": "discard"}}]
TARGETS
/bin/httpd -f -p 127.0.0.1:8080 -h /tmp/www > /tmp/httpd.log 2>&1 &
exec /bin/prometheus --config.file=/tmp/prom.yml --storage.tsdb.path=/tmp/data --web.listen-address=127.0.0.1:9090
"""
try:
 subprocess.run(
 ["docker", "run", "-d", "--rm", "--name", name, "--network", "none",
 "--entrypoint", "/bin/sh", "prom/prometheus:v3.5.1", "-c", script],
 check=True, capture_output=True, text=True, timeout=20,
 )
 eventually(lambda: value('up{job="discovered"}') == 1)
 targets = get_json('/api/v1/targets?state=any')["data"]
 assert len(targets["activeTargets"]) == 1 and len(targets["droppedTargets"]) == 1
 active = targets["activeTargets"][0]
 dropped = targets["droppedTargets"][0]
 assert active["discoveredLabels"]["__meta_filepath"] == "/tmp/targets/lab.json"
 assert dropped["discoveredLabels"]["role"] == "discard"
 labels = query('up{job="discovered"}')[0]["metric"]
 assert labels["discovery_file"] == "lab" and labels["role"] == "api"
 assert not any(label.startswith("__meta_") for label in labels)
 print(json.dumps({"active": 1, "dropped": 1, "stored_labels": labels,
 "source_file": active["discoveredLabels"]["__meta_filepath"]}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

程序等待真实采集发生，再检查一个活动目标与一个被过滤目标。活动目标的发现元数据包含 /tmp/targets/lab.json，保存的 up 序列具有 role="api" 和 discovery_file="lab"，没有遗留的 __meta_ 标签。另一个目标可以在过滤证据中看到，但没有被当成一次失败抓取。这些结果区分了候选输入、选择结果与最终存储身份。

全部请求留在容器回环地址，没有外部网络、宿主机挂载或公开端口，退出时删除唯一名称的容器。断言验证真实文件发现、过滤、元数据复制和最终标签，没有验证其他发现提供方的字段，也不能证明生产清单已经覆盖全部预期服务。

来源

Prometheus: configuration，有序目标重新标记与文件发现元数据，已核验 2026-09-13。
Prometheus: jobs and instances，目标身份与抓取生成指标，已核验 2026-09-13。
Prometheus: HTTP API，检查活动目标与被过滤目标，已核验 2026-09-13。