Prometheus · XB 现场笔记

注解解释告警现场，同时保留稳定身份

Tue, 22 Feb 2028 00:00:00 +0000

告警标签标识正在跟踪哪一个条件，并提供路由与分组字段；注解则解释这个条件，例如当前值、简短摘要或操作手册链接。把变化中的说明文字放进标签，可能把同一个持续问题拆成多个身份；反过来，如果责任归属字段只存在于注解中，依赖标签的路由又可能无法识别应该由谁处理。两类字段都重要，但承担不同职责。

区分身份与当前说明

队列告警可以保持 alertname、service 与 instance 标签稳定，同时把摘要从等待六项更新为等待八项。Alertmanager 可以在相同告警指纹下更新注解，而不是新增一条告警。指纹来自身份标签，不是通知渲染文本的哈希，所以文字改变不应该被直接理解为发生了另一个独立事件。这个边界也方便操作人员跟踪问题的持续变化。

该区别在进入 Alertmanager 之前也有影响。Prometheus 按告警标签集跟踪等待时长，如果标签中包含不断变化的当前值，就可能持续创建新身份，导致预期等待过程无法完成。除非数值确实定义另一种告警条件，否则应把它放在注解中。遇到反复等待却不触发的问题，应同时审阅规则标签和模板内容，而不是只调整等待参数。

一组告警未必拥有共同摘要

通知模板能访问多个层级的数据。GroupLabels 包含分组选择的标签，CommonLabels 包含通知中所有告警都具有的相同标签对，CommonAnnotations 同样只包含组内共有的注解。Alerts 列表则保留各成员自己的标签和注解，因此可以逐条解释不同实例的现场情况。共同字段与全部字段不是同一概念，字段存在于某条告警中也不保证它存在于组级对象中。

两个副本的摘要描述不同队列长度时，CommonAnnotations 就没有一个共同摘要。只打印该字段的模板，可能恰好省掉响应人员最需要的信息。更合理的方式是用共同上下文组织标题，再遍历每条告警输出变化中的说明。即使当前值不同，两条告警仍可能共享同一份操作手册链接，这个链接就可以继续作为共同注解使用。

也不能假定每一组都具有实例这样的分组标签。按服务与告警名分组，本来就是为了合并不同实例。模板应对应真实分组契约，并主动处理缺少共同字段的情况。代表性输入需要覆盖多条告警、不同注解，以及相关触发或恢复状态，不能只用一条理想告警验证，因为单条输入很容易让所有字段都碰巧成为共同字段。

注解更新也不等于立即发送新通知。Alertmanager 0.28.1 的去重判断关注触发与恢复的告警身份以及重复间隔，单独修改摘要不会产生新的指纹。可以在告警视图中保留持续变化的现场信息，却不能因此承诺每次数值更新都会发送一条消息。需要即时更新的业务应另行确认实际通知链路，而不是把文字变化当成发送触发器。

坏掉的样子

动态标签会让每次数值变化产生新指纹，增加告警变化量，并可能重新开始等待。匹配 team 的路由不能用同名注解代替标签；分组策略与模板假设不一致时，通知标题也可能只描述一台实例，正文却混入不同服务的告警。应把身份、分组与展示作为一条真实调用链检查，避免各部分单独看起来合理，组合后却误导读者。

模板语法通过，并不保证真实分组数据能渲染出完整且准确的消息。应核对渲染内容，而不是只检查解析成功。反过来，渲染成功也不能证明通知集成接受该消息，或消息已经送达。凭据与敏感请求详情不应放在注解中，因为这些文字可能被复制到路由选择的所有接收器，也可能进入后续通知记录。

快速验证

把程序保存为 annotations.py，在 Docker 可用时运行 python3 annotations.py。使用 Alertmanager 0.28.1，必要时下载镜像。隔离服务器的接收器没有实际发送集成；程序通过真实接口提交两条合成告警，然后在标签完全不变的情况下更新其中一条注解。操作只发生在本次临时服务器中，不会修改已有告警状态。

import http.client
import io
import json
import subprocess
import time
import uuid

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")


port = 9093
script = r"""set -eu
cat > /tmp/alertmanager.yml <<'ALERT_CONFIG'
route:
 receiver: preview
 group_by: [alertname, service]
 group_wait: 1h
 group_interval: 5m
 repeat_interval: 4h
receivers:
 - name: preview
ALERT_CONFIG
exec /bin/alertmanager --config.file=/tmp/alertmanager.yml --storage.path=/tmp/data \
 --web.listen-address=127.0.0.1:9093 --cluster.listen-address=
"""
try:
 subprocess.run(
 ["docker", "run", "-d", "--rm", "--name", name, "--network", "none",
 "--entrypoint", "/bin/sh", "prom/alertmanager:v0.28.1", "-c", script],
 check=True, capture_output=True, text=True, timeout=20,
 )
 eventually(lambda: request("GET", "/-/ready")[0] == 200)
 alerts = [{"labels": {"alertname": "QueueHigh", "service": "checkout", "instance": instance},
 "annotations": {"summary": "queue=" + str(depth), "runbook": "https://example.invalid/queue"}}
 for instance, depth in [("api-a", 6), ("api-b", 9)]]
 assert request("POST", "/api/v2/alerts", json.dumps(alerts))[0] == 200
 before = eventually(lambda: (a if len(a := get_json("/api/v2/alerts")) == 2 else False))
 fingerprints = {a["labels"]["instance"]: a["fingerprint"] for a in before}
 alerts[0]["annotations"]["summary"] = "queue=8"
 assert request("POST", "/api/v2/alerts", json.dumps([alerts[0]]))[0] == 200
 def updated_annotations():
 items = get_json("/api/v2/alerts")
 changed = any(x["labels"]["instance"] == "api-a" and
 x["annotations"]["summary"] == "queue=8" for x in items)
 return items if changed else None
 updated = eventually(updated_annotations)
 assert len(updated) == 2
 assert {a["labels"]["instance"]: a["fingerprint"] for a in updated} == fingerprints
 # Supply the documented notification Data shape to the real template renderer.
 data = {"receiver": "preview", "status": "firing",
 "groupLabels": {"alertname": "QueueHigh", "service": "checkout"},
 "commonLabels": {"alertname": "QueueHigh", "service": "checkout"},
 "commonAnnotations": {"runbook": "https://example.invalid/queue"},
 "alerts": [{"status": "firing", "labels": a["labels"], "annotations": a["annotations"]}
 for a in sorted(updated, key=lambda a: a["labels"]["instance"])]}
 template = '{{define "preview"}}{{.GroupLabels.service}}|common-summary={{with .CommonAnnotations.summary}}{{.}}{{else}}none{{end}}{{range .Alerts}}\n{{.Labels.instance}}:{{.Annotations.summary}}{{end}}{{end}}'
 for path, content in [("/tmp/preview.tmpl", template), ("/tmp/data.json", json.dumps(data))]:
 subprocess.run(["docker", "exec", "-i", name, "/bin/sh", "-c", "cat > " + path],
 input=content, text=True, capture_output=True, check=True, timeout=5)
 rendered = subprocess.run(["docker", "exec", name, "/bin/amtool", "template", "render",
 "--template.glob=/tmp/preview.tmpl", "--template.data=/tmp/data.json",
 '--template.text={{ template "preview" . }}'],
 text=True, capture_output=True, check=True, timeout=5).stdout.strip()
 assert rendered == "checkout|common-summary=none\napi-a:queue=8\napi-b:queue=9", rendered
 print(json.dumps({"alert_count": 2, "fingerprints_unchanged": True, "rendered": rendered}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

结果确认更新后仍只有两条告警，指纹也保持不变。程序随后向真实 amtool 模板渲染器提供文档规定的数据结构：共同注解故意只保留共享手册链接，不放入彼此不同的摘要。这里明确提供的输入验证渲染行为，不代表已验证服务器如何组装实际通知，更不能替代发送链路测试。

渲染标题显示 common-summary=none，之后分别出现 api-a:queue=8 与 api-b:queue=9。断言核对更新后的数值和逐条说明。全部 HTTP 请求只经过容器回环地址，不挂载宿主机目录，也不发布端口，退出时删除容器。生产通知仍应使用真实路由、模板数据和接收器集成进行验证，才能把展示正确与实际送达连起来。

本轮没有修改此运行实验，也没有重新执行。文中的预期输出和此前记录的观察，与本轮执行证据分别保留，不能据此声称真实集成已经再次通过。

来源

Alertmanager: notification template reference，分组标签、共同注解和逐条告警数据，已核验 2026-10-15。
Prometheus: alerting rules，标签标识告警，注解携带解释内容，已核验 2026-10-15。
Alertmanager 0.28.1: README，使用工具在本地渲染通知模板，已核验 2026-10-15。
Alertmanager 0.28.1 通知流水线，DedupStage 身份与重复间隔判断，已核验 2026-10-15。

记录规则保存按周期计算的查询结果

Wed, 26 Jan 2028 00:00:00 +0000

记录规则在指定评估时刻执行 PromQL 表达式，把结果作为一个新指标保存。反复刷新的面板可以读取这个指标，减少重复计算。但简单把它称为缓存，会遮住一个重要区别：记录序列有自己的样本历史、写入节奏和标签集合，并不是任意查询请求的透明缓存。使用者必须知道读到的是哪次预计算，以及这个结果保留了哪些信息。

三个时钟共同影响页面上的值

抓取决定原始观测何时进入存储，规则评估决定表达式何时生成记录样本，面板则决定何时以及以什么步长查询两者。把页面刷新得更快，不会让记录规则提前计算。因此，在两次规则评估之间读取记录指标，可能得到比同一时刻直接执行原表达式更旧的值。这是不同采样节奏的正常结果，不能仅凭两条曲线不同便断定计算错误。

规则组可以指定周期；未单独指定时，采用全局规则评估周期。同组规则按顺序执行，并使用相同的评估时间戳，所以后面的规则可以使用前面规则刚生成的结果。独立规则组即使写了相同的周期，也不能因此推导存在同样的先后顺序。依赖关系需要明确设计，不能依靠某次运行中碰巧出现的执行顺序。

预计算也改变了保留的数据

聚合表达式决定输出保留哪些维度。如果规则把 instance 求和消掉，面板之后就无法仅从这条记录序列恢复实例分布。仍需实例级排查时，应保留原始指标，并围绕已知消费者选择记录维度。每个剩余标签组合又是一条需要存储的新序列，因此把所有可能的聚合都做成规则，可能显著增加写入量和存储量，并不总是节省资源。

修改表达式会影响后续评估。正常重载规则不会用新定义重新计算全部旧样本，也不会自动填补规则创建之前的历史。在相同指标名下改变含义，可能让同一张图同时包含两套不兼容口径。应记录定义和时间窗口，在消费者要求历史可比时安排明确迁移，不能把正常重载解释为历史数据已经整体更新。

坏掉的样子

面板看起来停住，但原始样本仍在进入数据库时，应对照记录序列最近样本、规则组最近评估、执行耗时与错误。如果上一轮还没结束，下一次计划评估到来时会被跳过，直到当前轮完成或超时。把昂贵查询变成记录规则，只是把计算移入调度器，没有让计算成本消失。执行耗时长期接近周期时，新鲜度会比配置值更差。

查询变快也可能是因为聚合后回答的问题更窄。庆祝速度提升前，应确认被移除的维度确实不再需要。简单表达式通常不值得只为性能增加记录规则。应先测量重复查询成本和复用频率，再把新增序列、周期执行以及新鲜度延迟一起纳入判断。面板数量很多，也不等于每个表达式都必须预先保存。

快速验证

保存为 recording-cadence.py，运行 python3 recording-cadence.py。环境需要已经安装的 promtool，可以从 PATH 找到，或用 PROMTOOL 指定其可执行文件路径。本轮使用 Python 3.12.14 与 promtool 3.14.0。真实查询引擎在临时目录中评估合成样本，不启动服务器、监听端口或容器，也不联系外部服务。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

# Uses a real, installed promtool; no server or Docker runtime is started.
promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if not promtool:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")

tests = r"""evaluation_interval: 2m
rule_files:
 - rules.yml
tests:
 - interval: 1m
 input_series:
 - series: "queue_depth{queue=\"orders\"}"
 values: "1 4 9 16"
 promql_expr_test:
 - expr: "sum(queue_depth)"
 eval_time: 1m
 exp_samples:
 - labels: "{}"
 value: 4
 - expr: "queue:depth:sum"
 eval_time: 1m
 exp_samples:
 - labels: "{__name__=\"queue:depth:sum\"}"
 value: 1
 - expr: "queue:depth:sum"
 eval_time: 2m
 exp_samples:
 - labels: "{__name__=\"queue:depth:sum\"}"
 value: 9
 - expr: 'timestamp(queue:depth:sum)'
 eval_time: 1m
 exp_samples:
 - labels: '{}'
 value: 0
 - expr: 'timestamp(queue:depth:sum)'
 eval_time: 2m
 exp_samples:
 - labels: '{}'
 value: 120
 - expr: 'queue:depth:double'
 eval_time: 1m
 exp_samples:
 - labels: '{__name__="queue:depth:double"}'
 value: 2
 - expr: 'queue:depth:double'
 eval_time: 2m
 exp_samples:
 - labels: '{__name__="queue:depth:double"}'
 value: 18
"""
rules = r"""groups:
 - name: slow-recording
 interval: 2m
 rules:
 - record: queue:depth:sum
 expr: sum(queue_depth)
 - record: queue:depth:double
 expr: queue:depth:sum * 2
"""

with TemporaryDirectory(prefix="prometheus-query-check-") as directory:
 root = Path(directory)
 (root / "tests.yml").write_text(tests, encoding="utf-8")
 if rules:
 (root / "rules.yml").write_text(rules, encoding="utf-8")
 result = subprocess.run([promtool, "test", "rules", "tests.yml"],
 cwd=root, text=True, capture_output=True, timeout=45)
 print(result.stdout, end="")
 if result.returncode:
 print(result.stderr, end="")
 raise SystemExit(result.returncode)

预期输出为 SUCCESS。第一分钟原始求和结果是四，但记录值仍为第零分钟的一；第二分钟记录序列更新为九。这里故意选择很便宜的表达式，以隔离周期差异，不是在建议为每个队列仪表值建立记录规则，也没有测量真实调度器在负载下的性能。输入时间线和断言直接说明为何同一时刻两个查询可以返回不同结果。

执行结束后会删除临时测试文件。实验建立的是评估之间记录值与即时值可能合理不同这一事实。实际部署时，还需要确认规则加载、执行耗时、输出基数和消费查询。仅看到文件重载成功，并不能证明新指标已经积累了长时间面板所需的历史，也不能证明后续评估没有跳过或失败。

额外检查读取记录样本的时间戳：第一分钟仍是零，第二分钟变成一百二十秒。同组后续规则把前一条结果乘二，在这两个查询时刻分别得到二和十八。这些检查区分响应刚返回与存储观测刚更新，并实际覆盖同组依赖顺序。它们没有创建跨组调度保证，也没有模拟服务在负载下错过评估的行为。

来源

Prometheus: recording rules，保存评估结果、规则组周期和跳过评估，已核验 2026-10-15。
Prometheus: configuration，分别配置抓取与规则评估，已核验 2026-10-15。
Prometheus: unit testing rules，测试评估节奏与输入样本间隔，已核验 2026-10-15。

高基数标签在查询之前就增加存储序列

Mon, 10 Jan 2028 00:00:00 +0000

Prometheus 序列由指标名与完整标签集合识别。在计数器上增加客户或请求身份，即使所有面板都会立刻把这些身份求和，也仍可能创建大量序列。查询聚合改变返回结果，不会删除已经入库的原始序列。存储和写入成本在用户打开面板之前就已经产生，因此不能只看面板返回多少行来判断仪表化是否足够节制。

统计实际组合，而不是孤立取值

一个新的标签值，不是在整个数据库中自动对应一条新序列。它在指标名及其他标签形成不同组合的位置上，分别构成新身份。在明确指标与目标范围内，可能取值数的乘积给出笛卡尔组合上界；只有每种组合实际出现时，它才等于观测数量。维度之间存在约束时，上界可能远大于现实。真实数量还受到目标标签与指标族形态影响，不能把理论乘积直接宣称为已经发生的序列数量。

来自少量路由模板的标签可以有边界，包含标识符和查询参数的完整 URL 往往没有。客户身份、请求编号、任意错误文本和时间戳也需要明确审视。带多个桶序列的直方图，还会进一步放大每组标签组合的影响。预算应依据真实输出和预期工作负载，而不是只看某一个维度有多少取值，也不能因为每条样本数值很小便忽略身份成本。

查询少几行，不代表少存几行

按路由求和的表达式，可以读取十二条客户级序列后只返回三个结果，但十二条输入仍然存在。如果指标契约需要的就是路由总量，仪表化可以直接维护路由级计数器，只导出三条序列。这是在源头减少输出身份，不是要求每个消费者都重复隐藏额外维度。两种方式可能显示相同总数，却具有不同的数据保留和成本含义。

入库时删除标签不等于完成上述累计。不同样本可能获得同一个身份，而重新标记不会替它们决定如何相加。应使用明确的仪表化变更，或定义清楚的记录查询；后者会新增派生序列，原始数据仍按照存储策略保留。确实需要详细关联时，可以放入日志或追踪，但它们同样需要各自的权限、保留期限与成本约束，不是完全没有代价的替代存储。

使用正确范围的清单诊断增长

TSDB 状态接口提供头部统计，其中包括按指标名汇总的序列数量。这些值有助于定位大型指标族，但不是完整成本模型。采样间隔、标签长度、身份更替、数据块处理、保留策略和存储行为都会影响资源。不能把一个小实验中减少的序列比例，直接换算成生产内存或磁盘会减少的相同比例，更不能把该比例当成容量压测结果。

当一些头部序列已经没有近期可选择样本时，即时查询计数与头部序列统计可能不同；历史存储块又是另一种范围。比较报告时应记录测量时刻和统计总体。某次发布改变标签值后，旧身份仍可能留在存储中，因此查询当前返回更少结果，不代表之前的全部成本都已经消失。需要分别观察新增速度、当前可见序列和保留历史。

每次抓取的样本上限是保护措施，不是选择性聚合。指标重新标记之后仍超过该上限时，Prometheus 会把整个抓取视为失败，并不是悄悄保留一个便宜的子集。因此，保护资源的同时也可能失去有用观测。应根据真实输出制定预算，并对抓取失败设置清楚的信号，不能把限制触发后的缺失误解成业务没有流量。

坏掉的样子

新增无边界标签可能持续增加写入与内存压力，直到抓取或查询受到影响。应先定位指标族与仪表化改动，再从源头或经过审阅的样本过滤策略阻止不必要的新身份。立即删除历史数据不是所有场景都必须采用的恢复步骤，改变保留时间也不会瞬间清除全部资源成本。处理方式应依据实际瓶颈，而不是套用统一删除命令。

更隐蔽的失败是查询聚合很成功，面板看起来很小，但原始指标仍持续增长。应同时审阅导出身份和查询输出，为新增维度说明预期取值范围、有用消费者与负责人。生产计数器速率查询还应保留正确的重置处理；本实验用于比较固定总量的即时求和，不能代替先求速率再聚合的运行监控语义。

快速验证

保存程序为 cardinality.py，执行 python3 cardinality.py。需要 Docker 与 Prometheus 3.5.1，必要时下载镜像。本地文本端点为三个路由分别导出四个合成客户身份，同时独立导出已经累计好的路由总量。真实服务器抓取这些样本，并提供查询结果与 TSDB 统计，实验不会使用任何真实客户信息。

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: cardinality
 metrics_path: /metrics.txt
 static_configs:
 - targets: ['127.0.0.1:8080']

PROM_CONFIG
cat > /tmp/www/metrics.txt <<'METRIC_DATA'
# TYPE raw_requests_total counter
# TYPE bounded_requests_total counter
raw_requests_total{route="/orders",customer_id="synthetic-1"} 1
raw_requests_total{route="/orders",customer_id="synthetic-2"} 2
raw_requests_total{route="/orders",customer_id="synthetic-3"} 3
raw_requests_total{route="/orders",customer_id="synthetic-4"} 4
bounded_requests_total{route="/orders"} 10
raw_requests_total{route="/cart",customer_id="synthetic-1"} 1
raw_requests_total{route="/cart",customer_id="synthetic-2"} 2
raw_requests_total{route="/cart",customer_id="synthetic-3"} 3
raw_requests_total{route="/cart",customer_id="synthetic-4"} 4
bounded_requests_total{route="/cart"} 10
raw_requests_total{route="/search",customer_id="synthetic-1"} 1
raw_requests_total{route="/search",customer_id="synthetic-2"} 2
raw_requests_total{route="/search",customer_id="synthetic-3"} 3
raw_requests_total{route="/search",customer_id="synthetic-4"} 4
bounded_requests_total{route="/search"} 10

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('raw_requests_total')) == 12)
 assert value('count(raw_requests_total)') == 12
 assert value('count(bounded_requests_total)') == 3
 assert value('sum(raw_requests_total)') == value('sum(bounded_requests_total)') == 30
 raw_by_route = {x["metric"]["route"]: float(x["value"][1])
 for x in query('sum by (route) (raw_requests_total)')}
 bounded_by_route = {x["metric"]["route"]: float(x["value"][1])
 for x in query('bounded_requests_total')}
 assert raw_by_route == bounded_by_route
 statistics = get_json('/api/v1/status/tsdb')["data"]
 counts = {x["name"]: x["value"] for x in statistics["seriesCountByMetricName"]}
 assert counts["raw_requests_total"] == 12 and counts["bounded_requests_total"] == 3
 print(json.dumps({"raw_series": 12, "bounded_series": 3, "snapshot_total": 30,
 "per_route": raw_by_route, "tsdb_counts_confirmed": True}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

断言确认原始表示有十二条序列，受控表示有三条，两者总量都为三十，每个路由合计十。执行查询聚合之后，TSDB 仍报告十二条原始序列，证明返回结果变小没有擦除输入。隔离容器没有外部网络、宿主机挂载或公开端口，退出时删除。结果验证身份数量和算术，不是生产容量基准。

本轮没有修改此运行实验，也没有重新执行。文中的预期输出和此前记录的观察，与本轮执行证据分别保留，不能据此声称真实集成已经再次通过。

来源

Prometheus: data model，序列身份由指标名与标签集合组成，已核验 2026-10-15。
Prometheus: metric and label naming，受控维度与高基数标签建议，已核验 2026-10-15。
Prometheus: storage，头部数据、存储块与保留成本，已核验 2026-10-15。
Prometheus: HTTP API，按指标名称查看头部序列统计，已核验 2026-10-15。
Prometheus：配置，每次抓取的样本上限与重新标记冲突边界，已核验 2026-10-15。

Prometheus rate 估计计数器每秒的增长速度

Fri, 24 Dec 2027 00:00:00 +0000

请求计数器回答进程累计记录了多少事件，速率则回答这些事件到来得有多快。Prometheus 的 rate 估计指定范围内每秒平均增长量，修正能够观测到的计数器重置，并向范围边界进行外推。结果具有明确的时间单位，适合观察负载变化；但它不是两次抓取之间全部事件的精确还原，更不能凭空补回没有采到的重启历史。

采样决定能够推断多少事实

普通计数器在重置前持续增长，进程重启是常见的重置原因。相邻已观测样本出现下降时，计数器函数会按重置处理。不过，如果两次抓取之间已经重启并重新累计，而且新值超过旧样本，重置可能完全不可见。提高抓取频率可以提升观测分辨率，但任何查询都不能确定地恢复一段没有被记录的历史。

应先对每条计数器序列求 rate，然后聚合结果。如果先求和，一台实例的增长可能掩盖另一台实例的重置。标签决定序列身份，替换实例使用新标签时，是开始另一条序列，不是自动接续旧实例。队列长度等仪表值本来就允许正常下降，把它们交给计数器速率函数，会把真实下降错误解释为重置。

选择的范围也是指标含义的一部分

范围选择器左开右闭。在第五分钟求 [5m] 时，恰好位于第零分钟的样本不在范围内。对普通浮点计数器求速率至少需要两个可用样本；只有一个样本时得到空结果，并不表示业务流量为零。因此，范围不仅要覆盖正常抓取周期，还需要考虑偶发漏抓后的样本数量，不能仅凭希望曲线更灵敏就无限缩短。

较长窗口通常会平滑短促突发，也让突发离开平均值的时间更晚；较短窗口响应更快，但观测更少，而且可能变成空结果。应依据事件持续时间与检测目标选择范围，并在面板上明确标注。irate 使用最后两个样本，rate 使用所选范围，两者可以针对同一指标回答不同问题，只要面板清楚说明各自含义，不把数值当成同一种口径比较。

规则评估周期决定何时提出查询问题，不决定目标已经被抓取了多少次。如果目标每分钟才采集一次，即使面板每秒刷新，也不会凭空产生新的观测。分析告警响应速度时，需要分别检查采集与评估这两个周期，不能只缩短页面刷新时间。

坏掉的样子

刚创建的序列可能要等第二个样本到来后才出现在速率面板。把所有空值都补成零，可能掩盖采集故障。遇到空白，应先检查原始序列、时间戳和抓取状态，再判断业务是否空闲。另一种问题是窗口太长：短时间过载已经影响用户，但平均线被长窗口稀释，看起来始终平稳，告警因而没有达到阈值。

重置修正不代表缺口对准确性没有影响。漏抓可能隐藏突发或多次重启，范围边界的外推本身也属于估计。increase 以事件数量单位表达相应的范围估计，即使原始计数器只有整数，也可能返回小数。如果场景需要精确账务或计费总数，应依靠业务记账记录，不能把监控面板描述成可以完整重建交易流水的工具。

快速验证

保存为 rate.py，运行 python3 rate.py。环境需要已经安装的 promtool，可以从 PATH 找到，或用 PROMTOOL 指定其可执行文件路径。本轮使用 Python 3.12.14 与 promtool 3.14.0。真实查询引擎在临时目录中评估合成样本，不启动服务器、监听端口或容器，也不联系外部服务。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

# Uses a real, installed promtool; no server or Docker runtime is started.
promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if not promtool:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")

tests = r"""evaluation_interval: 1m
tests:
 - interval: 1m
 input_series:
 - series: "demo_requests_total{instance=\"steady\"}"
 values: "0+60x5"
 - series: "demo_requests_total{instance=\"restart\"}"
 values: "100 160 220 20 80 140"
 - series: "demo_requests_total{instance=\"gaps\"}"
 values: "0 60 _ 180 _ 300"
 - series: "demo_requests_total{instance=\"one\"}"
 values: "_ _ _ _ _ 7"
 - series: "combined_requests_total"
 values: "100 220 340 200 320 440"
 promql_expr_test:
 - expr: "rate(demo_requests_total{instance=\"steady\"}[5m])"
 eval_time: 5m
 exp_samples:
 - labels: "{instance=\"steady\"}"
 value: 1
 - expr: "abs(rate(demo_requests_total{instance=\"restart\"}[5m]) - 5/6) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{instance=\"restart\"}"
 value: 1
 - expr: "increase(demo_requests_total{instance=\"restart\"}[5m])"
 eval_time: 5m
 exp_samples:
 - labels: "{instance=\"restart\"}"
 value: 250
 - expr: "irate(demo_requests_total{instance=\"restart\"}[5m])"
 eval_time: 5m
 exp_samples:
 - labels: "{instance=\"restart\"}"
 value: 1
 - expr: "rate(demo_requests_total{instance=\"gaps\"}[5m])"
 eval_time: 5m
 exp_samples:
 - labels: "{instance=\"gaps\"}"
 value: 1
 - expr: "rate(demo_requests_total{instance=\"one\"}[5m])"
 eval_time: 5m
 exp_samples: []
 - expr: 'abs(sum(rate(demo_requests_total{instance=~"steady|restart"}[5m])) - 11/6) < bool 1e-12'
 eval_time: 5m
 exp_samples:
 - labels: '{}'
 value: 1
 - expr: 'abs(rate(combined_requests_total[5m]) - 7/3) < bool 1e-12'
 eval_time: 5m
 exp_samples:
 - labels: '{}'
 value: 1
"""
rules = r""""""

with TemporaryDirectory(prefix="prometheus-query-check-") as directory:
 root = Path(directory)
 (root / "tests.yml").write_text(tests, encoding="utf-8")
 if rules:
 (root / "rules.yml").write_text(rules, encoding="utf-8")
 result = subprocess.run([promtool, "test", "rules", "tests.yml"],
 cwd=root, text=True, capture_output=True, timeout=45)
 print(result.stdout, end="")
 if result.returncode:
 print(result.stderr, end="")
 raise SystemExit(result.returncode)

断言全部通过时输出 SUCCESS。稳定序列每秒增加一个请求。对于 100 160 220 20 80 140，五分钟 rate 为 5/6，increase 为二百五十，irate 为一。这些结果不同，是因为范围排除了最初样本，随后修正可见重置，再把所得到的平均增长外推到请求时长；二百五十不能被描述为原始样本直接观测到的增量。

带缺口的序列被故意设计为线性增长，因此仍得到每秒一，这个受控结果不能证明任意缺口都无害。只有一个样本的序列则返回空向量。测试分别验证数值与缺失状态，对循环小数使用数值容差。在将规则用于真实服务前，还应补充符合该服务特点的重启、稀疏流量和缺失数据案例，检查告警是否仍表达预期含义。

最后两项检查直接暴露聚合错误：稳定实例和重启实例分别求速率再合并，得到每秒 11/6；预先相加的样本流却得到 7/3，因为重置修正作用于已经混合的数据。两个计算都能成功执行，所以语法正确不证明计数器身份得以保留。程序明确给出混合前后数列与预期值，避免只靠口号说明先求速率的重要性。

来源

Prometheus: query functions，速率、增量、瞬时速率与重置修正，已核验 2026-10-15。
Prometheus: querying basics，范围边界与样本选择，已核验 2026-10-15。
Prometheus: unit testing rules，合成样本与表达式断言，已核验 2026-10-15。

Alertmanager 通过标签匹配树选择告警接收器

Wed, 08 Dec 2027 00:00:00 +0000

Alertmanager 根据告警标签遍历路由树，选择通知接收器。路由树表达责任归属与升级策略，接收器则定义实际通知集成。配置能够解析，并不代表每一类告警都被分配给正确目的地。因此，不能把重载成功当作路由有效的完成证据；应该先核对进入系统的标签契约，再验证整棵树针对典型告警的选择结果。

既要看匹配，也要看何时停止

每条告警都会进入必须匹配所有告警的根路由。子路由继承没有主动覆盖的配置；没有子节点匹配时，由当前节点处理。否则，遍历通常在第一个匹配的子节点后停止。匹配节点配置 continue: true，才允许继续检查后续同级节点。这不表示配置中的所有接收器都会获得同一条告警，未匹配的节点仍然不会参与。

一个路由节点只能指定一个接收器。接收器内部可以包含多个通知集成，多条匹配路由也可以选择不同接收器，两者是向多个目的地通知的不同方式。不能把路由的 receiver 字段直接换成列表，就期待具有相同行为。选择方案时应核对是否会重复通知，以及不同目的地是否需要独立的分组方式、升级策略和发送节奏。

责任归属依赖稳定的标签契约

匹配 team="payments" 的路由，需要进入 Alertmanager 的告警真正带有这个标签值。名为 team 的注解不能满足该条件。Prometheus 表达式中的聚合可能提前移除一个维度，所以应该检查最终告警标签，包括告警重新标记的影响，不能假定原始指标上的标签会原样保留到通知阶段。原始指标存在团队字段，不足以证明路由可以看到它。

根接收器应当对没有匹配具体子节点的告警仍然有用。这类告警也需要可观察的去向，以及能够修正分类的负责人。测试时除了已知团队，还应覆盖标签缺失：缺少团队的警告可能留在根节点，但缺少同一标签的严重告警仍可能命中独立的严重程度路由。是否缺失与是否完全没有匹配路径，是不同问题。

路由排列顺序本身就是行为。较宽泛的前置路由，可能让后面的具体路由根本没有机会被检查，除非启用了继续匹配。因此，即使匹配器文字没有变化，移动一段配置也可能改变收件方。顺序调整应按策略变化审阅，并把代表性标签输入与配置放在一起，以便持续核对预期选择。

按时间静默不会让匹配节点从遍历中消失。一个被静默的子节点在关闭继续匹配时，仍可能阻止后面的同级节点。因此，办公时间路由在不活跃时，不会自动变成值班路由的回退条件。升级策略需要同时审阅时间条件和树的停止规则，不能只看两个时段是否互补，就认为收件方一定连续覆盖。

坏掉的样子

拼写错误或标签改名可能使告警落到根接收器，新添加的宽泛子路由可能截走后面团队的告警，而不必要的继续匹配则可能让一个事件产生多份通知。诊断这些问题，需要实际标签和完整匹配路径，单独阅读某个节点通常不够。还应核对新增规则与既有顺序共同作用后的结果，而不只是新增部分自身是否正确。

接收器选择正确仍不等于送达。分组等待、静默、抑制、模板错误、传输故障和目的地行为，都可能在之后介入。先验证路由，再沿所选接收器追踪通知链路。增加规则等待时间不会修复团队匹配条件，缩短分组等待也不能修复接收器凭据缺失。每个阶段都需要对应证据，不能用前一阶段通过代替后一阶段结果。

快速验证

把程序保存为 routing.py，执行 python3 routing.py。需要 Docker 与公开的 Alertmanager 0.28.1 镜像，镜像缺失时可能先下载。真实 amtool 检查配置并验证七组标签输入。实验接收器只有名称，没有实际发送集成，因此可以检查路由选择而不会联系任何人员或外部服务，也不会影响现有告警系统。

import subprocess
import uuid

# Requires Docker and Alertmanager 0.28.1. No receiver has a delivery integration.
script = r"""set -eu
cat > /tmp/routes.yml <<'ROUTES'
route:
 receiver: default
 group_by: [alertname, service]
 routes:
 - receiver: payments
 matchers: ['team="payments"']
 continue: true
 - receiver: pager
 matchers: ['severity="critical"']
receivers:
 - name: default
 - name: payments
 - name: pager

ROUTES
/bin/amtool check-config /tmp/routes.yml
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=payments,pager team=payments severity=critical
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=payments team=payments severity=warning
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=pager team=data severity=critical
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=default team=data severity=warning
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=default severity=warning
/bin/amtool config routes test --config.file=/tmp/routes.yml --verify.receivers=default team=payments-preview severity=warning
sed 's/continue: true/continue: false/' /tmp/routes.yml > /tmp/stop.yml
/bin/amtool config routes test --config.file=/tmp/stop.yml --verify.receivers=payments team=payments severity=critical
"""
name = "xbcatm-route-test-" + uuid.uuid4().hex[:12]
try:
 result = subprocess.run(
 ["docker", "run", "--rm", "--name", name, "--network", "none", "-i",
 "--entrypoint", "/bin/sh", "prom/alertmanager:v0.28.1", "-s"],
 input=script, text=True, capture_output=True, timeout=30,
 )
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
print(result.stdout, end="")
if result.returncode:
 raise RuntimeError(result.stderr or result.stdout)
print("Verified seven route cases, including continuation and unmatched labels.")

第一组结果为 payments,pager：支付团队路由先匹配并继续，严重程度路由随后也匹配。支付团队警告只选择支付接收器，数据团队严重告警选择呼叫接收器；没有匹配或缺少团队值的相应输入进入根接收器。payments-preview 不会匹配精确的支付团队值，避免把名称相近误认为条件成立。

最后一项把继续匹配改为关闭，确认支付团队严重告警现在只选择支付接收器。每组结果都由 --verify.receivers 强制核对，出现差异会直接使执行失败。容器没有外部网络，不挂载宿主机目录，退出时自动移除。真实接收器的通知送达仍需要另行安排受控验证，这份结果只证明路由选择。

本轮没有修改此运行实验，也没有重新执行。文中的预期输出和此前记录的观察，与本轮执行证据分别保留，不能据此声称真实集成已经再次通过。

来源

Alertmanager: configuration，路由继承、同级继续匹配与接收器定义，已核验 2026-10-15。
Alertmanager 0.28.1: README，配置与路由检查工具，已核验 2026-10-15。
Prometheus: Alertmanager，路由、分组与通知抑制的职责，已核验 2026-10-15。

Prometheus 规则先跟踪告警状态，再交给通知链路

Wed, 01 Sep 2027 00:00:00 +0000

告警规则评估 PromQL 表达式，并持续跟踪表达式返回的标签集。Prometheus 判断每个告警是等待还是触发，Alertmanager 接收告警信息后负责通知路由、分组、静默与抑制。排查时应分别追踪这些环节：规则显示正在触发，是规则状态的证据，不能直接证明某个人已经收到消息。把状态和送达混为一谈，会使漏通知问题很难定位。

表达式返回元素就会激活告警候选项

表达式返回的每个元素代表一个活动告警候选项。queue_depth > 5 这样的比较会过滤不满足条件的数值；但加上 bool 修饰符之后，不满足条件的比较仍会留下数值为零的元素。告警规则依据元素是否存在来激活候选项，因此误用该修饰符，可能让数值已经为零的结果也进入告警流程。这是查询看似合理、规则却持续激活的常见原因。

标签定义告警身份。服务、队列与严重程度等稳定路由维度适合放在标签中，变化中的说明值则适合放在注解中。如果把当前队列大小写进标签，每次数值变化都可能创建一个新身份，重新开始等待。把大小写进注解则可以解释现场状态，同时保留原有告警身份。需要审阅的不只是阈值，还有标签和注解承担的职责。

等待时长通过评估时刻观察

配置 for: 2m 后，一个新出现的标签集会先等待，直到它在评估中持续活动两分钟。如果规则每分钟评估一次，第一分钟首次看到异常，就可能在第三分钟进入触发状态。引擎观察的是评估结果，不是样本之间连续发生的全部物理事实。因此，实际发现时间还包括等待下一次评估的时间，不能只用配置的等待时长计算最坏延迟。

省略 for 时，活动表达式可以在第一次评估就触发。这可能适合含义明确且必须立即处理的故障，但也意味着一个异常样本便足够触发。应根据失败语义主动选择，而不是由于忘记配置而意外采用默认行为。

若表达式在触发前不再返回该标签集，等待状态会清除。本例采用默认恢复行为，已经触发的告警也会在条件消失后清除。显式配置 keep_firing_for 可以在条件消失后继续保持一段触发时间，但本实验没有使用这个选项。不能把所有告警都描述为必须人工确认才能消除的事故记录；规则状态和事故管理系统的关闭流程是不同概念。

坏掉的样子

对缺失序列做阈值比较通常返回空结果。这可能让告警清除，但应用其实已经停止输出指标。应明确缺失是否需要独立规则，不能一律当成恢复。在测试阈值上下变化的同时，也要测试标签变更与样本缺失。语法检查只能证明文件能够解析，并不能揭示这类条件含义错误，更不能证明规则在真实数据中一定符合预期。

告警已经触发却没有页面通知，原因可能是静默、抑制、路由选择、分组等待或发送失败。这些机制属于通知链路，不会改变 Prometheus 对阈值的评估。应先查看活动告警标签，再查看 Alertmanager 匹配了哪个接收器，以及是否真正产生送达证据。延长 for 不会修复接收器配置错误，也不会自动补上路由所需但缺少的标签。

快速验证

把下面程序保存为 alert-state.py，在 PATH 中准备已安装的 promtool，或用 PROMTOOL 指定其可执行文件，再运行 python3 alert-state.py。完整程序在 promtool 3.14.0 与 Python 3.12.14 上通过，直接在本地评估真实规则，不需要 Docker，不启动监听端、Alertmanager 或外部通知目标，也不会向他人发送消息。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if promtool is None:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")
promtool = str(Path(promtool).resolve())
tests = r"""evaluation_interval: 1m
rule_files:
 - rules.yml
tests:
 - interval: 1m
 input_series:
 - series: "queue_depth{queue=\"orders\"}"
 values: "0 6 6 6 0 6 0 0"
 promql_expr_test:
 - expr: 'sum(ALERTS{alertname="BooleanTrap",alertstate="firing"}) or vector(0)'
 eval_time: 0m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\",alertstate=\"pending\"}) or vector(0)"
 eval_time: 1m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\",alertstate=\"firing\"}) or vector(0)"
 eval_time: 2m
 exp_samples:
 - labels: "{}"
 value: 0
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\",alertstate=\"firing\"}) or vector(0)"
 eval_time: 3m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\"}) or vector(0)"
 eval_time: 4m
 exp_samples:
 - labels: "{}"
 value: 0
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\",alertstate=\"pending\"}) or vector(0)"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "sum(ALERTS{alertname=\"QueueBacklog\"}) or vector(0)"
 eval_time: 6m
 exp_samples:
 - labels: "{}"
 value: 0
 - interval: 1m
 input_series:
 - series: 'queue_depth{queue="orders"}'
 values: "6 6 stale"
 promql_expr_test:
 - expr: 'sum(ALERTS{alertname="QueueBacklog"}) or vector(0)'
 eval_time: 2m
 exp_samples:
 - labels: "{}"
 value: 0
"""
rules = r"""groups:
 - name: queue-alerts
 interval: 1m
 rules:
 - alert: QueueBacklog
 expr: queue_depth{queue="orders"} > 5
 for: 2m
 labels:
 severity: page
 annotations:
 summary: Orders queue remains above five
 - alert: BooleanTrap
 expr: queue_depth{queue="orders"} > bool 5
 annotations:
 summary: Deliberately incorrect boolean alert for this test
"""
with TemporaryDirectory(prefix="prom-rule-test-") as directory:
 work = Path(directory)
 (work / "tests.yml").write_text(tests, encoding="utf-8")
 (work / "rules.yml").write_text(rules, encoding="utf-8")
 subprocess.run([promtool, "test", "rules", "tests.yml"], cwd=work,
 check=True, timeout=45)

预期输出是 SUCCESS。第一分钟告警进入等待，第二分钟尚未触发，第三分钟触发；第四分钟条件恢复，不再有活动的 ALERTS 元素。第五分钟第二次短促升高再次进入等待，第六分钟便恢复，因此这一波不会达到触发状态。两次变化共享同一个队列身份，可以直接检查等待是否在恢复后重新开始。

断言检查的是系统生成的 ALERTS 序列，其中 or vector(0) 仅用于在测试中把没有活动元素表示成可比较的零，不是生产告警表达式的一部分。刻意写错的 BooleanTrap 规则在第零分钟比较为假时仍然触发；独立的陈旧标记样本则在触发前清除等待状态。后者验证显式陈旧标记，不能代表所有抓取失败时间线。临时规则文件在结束后清理，实验验证的是给定时间线的状态转换；接收器匹配、分组延迟与实际消息送达，仍需使用目标 Alertmanager 配置单独测试，不能从规则通过推导出来。

来源

Prometheus: alerting rules，活动标签集、等待时长和系统生成的 ALERTS 序列，已核验 2026-10-15。
Prometheus: unit testing rules，评估时间线与断言输入，已核验 2026-10-15。
Prometheus: Alertmanager，通知分组、路由、静默和抑制，已核验 2026-10-15。

记录规则应保留比例的分子和分母

Tue, 31 Aug 2027 00:00:00 +0000

当查询成本和复用频率足以支持预计算时，反复使用的服务级查询适合做成记录规则。关键问题是保存什么。如果只保存每个实例的错误百分比，可能丢掉之后聚合必需的流量规模；同时保存错误速率与请求速率，则保留了分子和分母，消费者能够据此计算按实际请求量加权的服务错误占比，而不是把每台实例当成相同流量。

百分比必须对应明确的总体

假设繁忙实例每秒处理十个请求，每秒发生零点一个错误；空闲实例每秒处理一个请求，却每秒发生零点五个错误。两个实例的错误占比分别为百分之一与百分之五十。直接平均得到百分之二十五点五，相当于给两个实例相同权重，但它们的请求量实际上相差十倍。这个数描述平均实例百分比，不描述服务处理的全部请求。

服务合计每秒处理十一个请求，发生零点六个错误，因此错误占比是 0.6/11，约百分之五点四五。这是聚合错误量除以聚合请求量。两侧必须描述同一组符合条件的流量，并使用相同时间窗口。如果分子排除了分母包含的一类失败，或者两侧聚合了不同服务，面板即使计算得很快，结果也仍然不成立。

按顺序建立规则依赖

先对每条计数器序列应用 rate，使已经观测到的重置能够在聚合前得到处理，再按照消费者确实需要的维度求和。本例依次记录服务与实例维度的请求速率、服务请求速率、服务错误速率，以及最终服务错误占比。第一个实例级中间结果用于展示明确的前后依赖，后续规则实际消费这个结果，而不是重复写一个看似相关的名字。

四条规则位于同一个组，按声明顺序运行，使用相同评估时间。分子与分母都保留匹配的 service 标签，因此除法能够把对应服务配对。如果分母额外保留实例标签，就会改变向量匹配关系，可能导致没有结果，或需要重新设计连接方式。测试应同时检查输出标签和数值，不能只看到一个合理百分比就认为查询正确。

命名应说明聚合层级和范围。两分钟速率与三十分钟速率即使当前值恰好相同，也不是同一种量。应在规则旁记录哪些事件计入总体，并明确消费它的面板与告警。沿用旧名称但修改公式，只会改变未来记录样本，不会重新解释已经写入的历史。需要保持时间可比性时，定义变更必须被消费者看见。

坏掉的样子

平均百分比可能让一台低流量故障实例主导整个服务报告，也可能掩盖高流量实例的失败。提高评估频率不会修复这个算术问题，应恢复底层计数或速率，在分别聚合后再相除。如果最后只保留了百分比，通常无法仅靠这些百分比重建原始流量权重，因为相同占比可以来自完全不同的请求数量。

零流量是另一类情况。分母为零时，错误占比并没有被定义为零；分子缺失也可能代表仪表化缺少序列，而不是没有错误。应根据指标契约明确这些语义，避免自动把所有空结果或未定义数值显示成健康的零。还应确认健康期间错误计数器是否持续导出，避免只有发生错误后才创建序列，导致正常状态与数据缺失难以区分。

快速验证

保存为 recording-weighted.py，在 PATH 中准备已安装的 promtool，或用 PROMTOOL 指定可执行文件，再运行 python3 recording-weighted.py。完整程序在 promtool 3.14.0 与 Python 3.12.14 上通过。真实规则引擎评估每分钟一份的合成计数器，包含权重明显不同的实例，以及独立的零流量、序列缺失案例。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if promtool is None:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")
promtool = str(Path(promtool).resolve())
tests = r"""evaluation_interval: 1m
rule_files:
 - rules.yml
tests:
 - interval: 1m
 input_series:
 - series: "http_requests_total{service=\"checkout\",instance=\"busy\"}"
 values: "0+600x5"
 - series: "http_errors_total{service=\"checkout\",instance=\"busy\"}"
 values: "0+6x5"
 - series: "http_requests_total{service=\"checkout\",instance=\"quiet\"}"
 values: "0+60x5"
 - series: "http_errors_total{service=\"checkout\",instance=\"quiet\"}"
 values: "0+30x5"
 promql_expr_test:
 - expr: "service:http_requests:rate2m"
 eval_time: 5m
 exp_samples:
 - labels: "{__name__=\"service:http_requests:rate2m\",service=\"checkout\"}"
 value: 11
 - expr: "abs(service:http_errors:rate2m - 0.6) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{service=\"checkout\"}"
 value: 1
 - expr: "abs(service:http_errors:ratio_rate2m - 0.6/11) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{service=\"checkout\"}"
 value: 1
 - expr: "abs(avg(rate(http_errors_total[2m]) / rate(http_requests_total[2m])) - 0.255) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - interval: 1m
 input_series:
 - series: 'http_requests_total{service="idle",instance="one"}'
 values: "0+0x5"
 - series: 'http_errors_total{service="idle",instance="one"}'
 values: "0+0x5"
 promql_expr_test:
 - expr: 'count(service:http_errors:ratio_rate2m != service:http_errors:ratio_rate2m)'
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - interval: 1m
 input_series: []
 promql_expr_test:
 - expr: 'count(service:http_errors:ratio_rate2m) or vector(0)'
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 0
"""
rules = r"""groups:
 - name: service-rates
 interval: 1m
 rules:
 - record: instance:http_requests:rate2m
 expr: sum by (service, instance) (rate(http_requests_total[2m]))
 - record: service:http_requests:rate2m
 expr: sum by (service) (instance:http_requests:rate2m)
 - record: service:http_errors:rate2m
 expr: sum by (service) (rate(http_errors_total[2m]))
 - record: service:http_errors:ratio_rate2m
 expr: service:http_errors:rate2m / service:http_requests:rate2m
"""
with TemporaryDirectory(prefix="prom-rule-test-") as directory:
 work = Path(directory)
 (work / "tests.yml").write_text(tests, encoding="utf-8")
 (work / "rules.yml").write_text(rules, encoding="utf-8")
 subprocess.run([promtool, "test", "rules", "tests.yml"], cwd=work,
 check=True, timeout=45)

预期输出为 SUCCESS。记录请求速率为十一，错误速率为零点六，最终占比为 0.6/11。另外一项断言明确展示，错误的实例比例平均法得到 0.255。涉及浮点除法的比较使用很小的数值容差，标签断言则确认仍保留 checkout 服务身份。这些检查同时覆盖计算次序、依赖输出和最终聚合口径。

零流量案例得到 NaN，它与自身比较不相等，因此过滤比较保留一条序列；输入缺失时则没有比例序列，两者都不应被当成健康的零。这个本地规则测试不启动监听端，临时文件会清理。它不是性能基准，也不能证明生产仪表化完整。部署前还应补充符合服务实际的重置和入库延迟案例，并测量查询成本及规则耗时，再判断是否有运行收益。

来源

Prometheus: recording rules，有顺序的规则依赖与保存结果，已核验 2026-10-15。
Prometheus: query functions，先计算速率再聚合以识别计数器重置，已核验 2026-10-15。
Prometheus: unit testing rules，验证记录序列与查询结果，已核验 2026-10-15。

Prometheus 主动抓取指标，并记录抓取结果

Mon, 30 Aug 2027 00:00:00 +0000

Prometheus 会主动请求每个已配置目标的 HTTP 指标端点。目标负责暴露观测值，采集器决定抓取时刻、解析响应并保存样本。这种安排让采集故障能够从采集器一侧被看见，但不能保证端点一定可达、所有预期目标都被发现，也不能保证用户的登录或下单流程正常。理解这些边界，才能把采集结果转换成准确的告警和排查动作。

一个任务包含多个独立抓取的实例

任务通常把用途相同的目标组织在一起，例如一组接口服务副本。每个目标仍是独立实例，具有自己的抓取结果。常见的 job 与 instance 标签标识这层上下文，最终标签也可能经过重新标记而改变。服务发现提供候选目标，抓取配置再决定实际访问的端点、协议、周期、超时和认证方式。因此，目标没有被发现与目标已经配置但抓取失败，是两类不同的问题。

采集器必须能够连接目标。虽然导出器不需要主动向采集器上传指标，目标仍然需要允许经过授权的采集器访问其入站端口。网络策略、证书身份、认证凭据与路由不会因为采用拉取模式而消失。拉取只是改变连接由哪一方发起，不能把任意导出器变成可以直接暴露在公网的安全接口。部署时要从采集器所在网络检查这条路径。

准确理解系统生成的指标

对于已配置的实例，Prometheus 会生成 up 指标，抓取成功时为一，失败时为零。它是指标名称，不是所谓的 up 标签。抓取耗时与样本数量则补充了采集质量的证据。导出器可能在后端数据库不可用时仍返回合法响应，也可能漏掉一项重要业务指标，因此即使 up 为一，也不能推导后端依赖和全部业务观测都正常。

这些进一步的问题应由应用结果指标、导出器专门提供的依赖状态，以及实际业务探测回答。反过来，up=0 描述的是采集失败，监控网络故障可能使它变为零，而用户请求仍然成功。告警措辞应写清采集目标与错误证据，避免让响应人员把所有监控链路问题直接当成客户故障。业务影响仍需要另一组证据确认。

指标重新标记不会应用于 up 这类自动生成序列。因此，即使过滤掉了全部业务样本，也可能仍然看到抓取成功。调整过滤规则时，应把预期指标族或样本量纳入验收，分清主动丢弃观测与导出器故障。一个绿色采集指标不能证明过滤后的业务数据仍满足面板和告警所需的契约。

坏掉的样子

连接被拒绝、请求超时、证书校验失败或导出格式无效，都可能让抓取失败。先查看目标的最近抓取错误，再决定需要调整什么。延长周期无法修复错误端口；增大超时可能让缓慢的导出器看起来恢复，却不会消除它的执行成本。采集变贵时还应检查输出序列数量和响应大小，确认是否新增了不必要的标签组合或昂贵查询。抓取超时不能超过配置周期，缩短周期前则应评估导出器负载。更快的轮询可能成倍增加导出器对数据库的查询次数，却不会降低每次查询的成本。

从服务发现中移除的目标，与继续存在但返回零的目标不同。前者的对应序列之后可能不再出现在即时查询中，所以把全站 up 求和，并不能证明所有预期实例仍然存在。需要完整性保证时，应把发现结果与实际部署清单对照。单独请求一次 /metrics 成功，同样不能代替登录、支付或订单提交的功能验证。

快速验证

把下面程序保存为 pull.py，在 Docker 可用的环境执行 python3 pull.py。程序使用 prom/prometheus:v3.5.1，如果本机尚未缓存镜像，首次运行需要从镜像仓库下载。实验只创建一个一次性容器，让其中的 Prometheus 抓取自己的回环端点，以及回环地址上没有服务监听的端口。它不发布宿主机端口，容器也无法访问外部网络。

import json
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
scrape_configs:
 - job_name: self
 static_configs:
 - targets: ['127.0.0.1:9090']
 - job_name: refused
 static_configs:
 - targets: ['127.0.0.1:1']
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=count%28up%29%20%3D%3D%202%20and%20sum%28up%29%20%3D%3D%201'; then
 if grep -q '"status":"success"' /tmp/ready.json && ! grep -q '"result":\[\]' /tmp/ready.json; then
 wget -qO- 'http://127.0.0.1:9090/api/v1/query?query=up'
 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)
payload = json.loads(result.stdout)
assert payload["status"] == "success"
values = {item["metric"]["job"]: float(item["value"][1])
 for item in payload["data"]["result"]}
assert values == {"self": 1.0, "refused": 0.0}, values
print(json.dumps({"up_by_job": values, "scrape_reachability_only": True}, indent=2))

结果应当包含 self: 1.0 和 refused: 0.0。程序等待两个目标都有抓取结果，再通过查询接口进行断言，因此不会把启动期间数据库暂时为空误判成配置失败。退出清理仅针对本次随机命名的容器，不涉及其他容器。这个结果证明真实采集器可以区分成功抓取与连接拒绝；它没有测试业务功能，也没有证明服务发现清单完整。

让结果指向具体排查动作

实际故障中，先定位失败实例并阅读抓取错误，再从采集器的网络环境检查连接路径。能够拿到响应时，应核对格式、内容类型和导出器依赖状态，而不是只看端口是否开放。复制诊断结果时要去掉凭据。恢复后同时确认 up 与面板实际使用的业务序列：前者恢复不代表后者一定重新出现，遗漏指标仍可能让面板显示空白。

本轮没有修改此运行实验，也没有重新执行。文中的预期输出和此前记录的观察，与本轮执行证据分别保留，不能据此声称真实集成已经再次通过。

来源

Prometheus: jobs and instances，抓取生成指标与目标身份，已核验 2026-10-15。
Prometheus: configuration，抓取周期、超时和目标配置，已核验 2026-10-15。
Prometheus: HTTP API，即时查询的响应格式，已核验 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。

Alertmanager 分组组织告警，静默抑制通知

Tue, 27 Jul 2027 00:00:00 +0000

一个事故可能产生很多告警，但一组告警并不能证明它们具有同一个原因。Alertmanager 根据配置的标签与路由上下文组织告警，便于一起处理通知，组内仍然保留各条告警的独立身份。静默则是另一种操作：在指定时间窗口内抑制匹配通知，并不会替应用解决故障。理解这些差异，才能准确解释告警页面与通知数量的变化。

分组键决定哪些细节放在一起

配置 group_by: [alertname, service] 时，两条属于结算服务的 QueueHigh 告警可以进入同组，即使实例标签不同。搜索服务的 QueueHigh 属于另一组，结算服务的 DiskFull 也因为告警名不同而单独成组。分组依据被选择的标签值，不要求所有成员具有完全相同的指纹。通知被合并后，实例级细节仍然可以从成员列表查看。

把实例加入分组键会增加组数，也可能抵消跨副本合并的目的；省略服务又可能把不同负责人或工作负载混在一起。应围绕排查方式和责任归属选择分组键，同时保留查看成员的入口。特殊值 ... 表示使用所有标签分组，实际效果接近关闭更大范围的聚合，不能把它当作自动寻找合理分组方式的通配符。

路由上下文同样重要。发往不同接收器的告警，即使所选分组标签相同，也不一定组成同一份通知。应验证路由与分组的组合行为。负责整个服务的接收器可能适合合并多个实例，另一个集成则可能需要不同分组契约。任何一种设置都不会自动证明这些告警具有相同根因，因果关系仍然需要从事件与运行证据判断。

初次等待、组内变化和重复提醒使用不同计时

group_wait 延迟新组的第一份通知，让相近时间到来的告警可以加入。某条告警若在初次等待结束前已经恢复，可能完全不产生通知。group_interval 决定之后检查组内更新的节奏，包括新增触发成员或恢复成员；它不是承诺每隔这么久无条件重发所有尚未结束的组。

没有新增触发或恢复的告警身份需要更新时，repeat_interval 控制重复提醒；单独改变注解文字并不一定触发新通知。是否到达重复时机是在组周期上检查的，因此应选择兼容的整数倍，而不是把它理解为完全独立且精确的闹钟。发送处理与失败还可能增加延迟。应依据响应目标设置这些参数，并将规则等待时长与通知调度分别考虑，避免只看其中一个参数就承诺发现到送达的时间。

通知历史同样存在保留边界。如果 repeat_interval 超过 Alertmanager 的数据保留时间，文档说明可能按保留边界重复发送。因此，把提醒间隔设置得很长，不保证这段时间里绝无重复消息。通知日志的保留期限，与具有明确结束时间的静默，是不同生命周期，应分别纳入运行检查。

坏掉的样子

分组太细，会让一组副本故障产生很多通知；分组太宽，又可能看不出具体服务需要处理。页面只显示一个组，不意味着只剩一条告警。判断事故是否改善前，应展开成员并核对分组键，不能把通知变少直接当成故障减少的证据。通知数量也可能只是由策略变更或抑制行为造成。

静默条件过宽，可能抑制计划维护范围之外的告警。应限制时间窗口，并检查哪些活动告警实际匹配。静默到期只是恢复通知资格，不会修复应用，也不保证立即发出一条消息。抑制规则则是独立的配置关系，由活动的源告警抑制匹配目标通知，与人工设置有时限静默不同，不能把两者的原因和结束条件混为一谈。

快速验证

把程序保存为 grouping.py，在 Docker 可用时执行 python3 grouping.py。使用 Alertmanager 0.28.1，必要时获取镜像。真实接口接收四条合成告警。接收器没有发送集成，初次通知等待也故意设置得很长，因此实验只观察分组和抑制状态，不会向外部发送消息，也不接触已有告警实例。

import http.client
import io
import json
import subprocess
import time
import uuid

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")


from datetime import datetime, timedelta, timezone

port = 9093
script = r"""set -eu
cat > /tmp/alertmanager.yml <<'ALERT_CONFIG'
route:
 receiver: preview
 group_by: [alertname, service]
 group_wait: 1h
 group_interval: 5m
 repeat_interval: 4h
receivers:
 - name: preview
ALERT_CONFIG
exec /bin/alertmanager --config.file=/tmp/alertmanager.yml --storage.path=/tmp/data \
 --web.listen-address=127.0.0.1:9093 --cluster.listen-address=
"""
try:
 subprocess.run(
 ["docker", "run", "-d", "--rm", "--name", name, "--network", "none",
 "--entrypoint", "/bin/sh", "prom/alertmanager:v0.28.1", "-c", script],
 check=True, capture_output=True, text=True, timeout=20,
 )
 eventually(lambda: request("GET", "/-/ready")[0] == 200)
 labels = [
 {"alertname": "QueueHigh", "service": "checkout", "instance": "api-a"},
 {"alertname": "QueueHigh", "service": "checkout", "instance": "api-b"},
 {"alertname": "QueueHigh", "service": "search", "instance": "api-c"},
 {"alertname": "DiskFull", "service": "checkout", "instance": "api-a"},
 ]
 assert request("POST", "/api/v2/alerts", json.dumps([{"labels": x} for x in labels]))[0] == 200
 groups = eventually(lambda: (groups if len(groups := get_json("/api/v2/alerts/groups")) == 3 else False))
 sizes = {g["labels"]["service"] + "/" + g["labels"]["alertname"]: len(g["alerts"]) for g in groups}
 assert sizes == {"checkout/QueueHigh": 2, "checkout/DiskFull": 1, "search/QueueHigh": 1}
 now = datetime.now(timezone.utc)
 silence = {"matchers": [{"name": "service", "value": "checkout", "isRegex": False, "isEqual": True}],
 "startsAt": (now - timedelta(seconds=1)).isoformat(),
 "endsAt": (now + timedelta(minutes=10)).isoformat(),
 "createdBy": "local-fixture", "comment": "Disposable grouping test"}
 status, body = request("POST", "/api/v2/silences", json.dumps(silence))
 assert status == 200
 silence_id = json.loads(body)["silenceID"]
 def silenced_state():
 alerts = get_json("/api/v2/alerts")
 count = sum(silence_id in x["status"]["silencedBy"] for x in alerts)
 return alerts if count == 3 else None
 alerts = eventually(silenced_state)
 assert len(alerts) == 4
 assert all((silence_id in x["status"]["silencedBy"]) == (x["labels"]["service"] == "checkout") for x in alerts)
 assert request("DELETE", "/api/v2/silence/" + silence_id)[0] == 200
 def unsilenced_state():
 alerts = get_json("/api/v2/alerts")
 return len(alerts) == 4 and all(silence_id not in x["status"]["silencedBy"] for x in alerts)
 eventually(unsilenced_state)
 print(json.dumps({"group_sizes": sizes, "silenced_alerts": 3,
 "alerts_remain_visible": 4, "silence_expired": True}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

输出应显示三个组：结算服务的 QueueHigh 有两个成员，结算服务的 DiskFull 有一个，搜索服务的 QueueHigh 也有一个。随后，临时静默匹配结算服务，抑制三条告警，但四条告警仍然都能通过接口看到；搜索服务告警不在静默范围内。程序再主动结束静默，并确认各告警的静默标识列表中不再包含该标识。

所有请求只经过容器回环地址，不发布宿主机端口，也不挂载目录，清理仅删除本次唯一名称的容器。这些断言验证成员关系与静默生命周期，没有测量通知计时精度，没有验证抑制规则，也没有证明下游送达。相关行为仍需使用实际路由、调度与接收器配置另行测试，才能得到对应的完成证据。

来源

Alertmanager: configuration，分组键、通知周期与抑制规则，已核验 2026-10-15。
Prometheus: Alertmanager，分组与静默的语义，已核验 2026-10-15。
Alertmanager 0.28.1: README，第二版接口与本地运行方式，已核验 2026-10-15。
Alertmanager 0.28.1 通知流水线，DedupStage 身份与重复间隔判断，已核验 2026-10-15。

外部标签标识 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。

Pushgateway 保留批任务指标，直到生命周期被主动处理

Thu, 13 May 2027 00:00:00 +0000

短生命周期任务可能在 Prometheus 下一次抓取之前就结束。Pushgateway 提供中间层，保留任务推送的指标以供后续抓取，但它不是每个短进程的默认方案。Prometheus 主要建议把它用于适当的服务级批任务结果。保留数据的生命周期与任务自身独立，因此抓取成功不能证明任务最近运行过，也不能证明业务工作已经成功完成。

为稳定的批任务结果建立身份

夜间对账这样的服务级任务，可以把最近结果发布到稳定分组键下。如果把新的运行编号、时间戳或机器身份放进键中，每次运行都可能创建额外分组，而不是更新同一份结果。Pushgateway 没有自动清理旧分组的过期时间机制，负责人需要明确替换或删除相关数据，不能假定退出任务后数据也会跟着消失。

与具体机器相关的批任务，往往可以使用节点导出器的文本文件采集器。共享网关本身也增加了可用性依赖。它的 up 表示 Prometheus 能否抓取网关，不表示每个原始推送任务都健康。应根据观测事件与清理责任选择采集方式，而不是把推送当成绕过服务发现或网络策略的通用办法。任务语义没有确定时，先增加网关并不会自动解决监控定义。

替换范围由 HTTP 方法决定

URL 路径定义分组键，包括任务名称与其他标签对。HTTP PUT 替换这个精确分组中的指标；POST 则替换本次请求包含的同名指标族，同时保留组内其他指标族。POST 不表示给原值递增，也不是向持久事件日志追加一条记录。如果一次报告把数值从七写成九，结果是九，而不是自动累加成十六。

DELETE 删除 URL 标识的精确分组。仅删除任务名构成的分组键，不会删除所有同时包含该任务名和额外标签的分组。网关文档规定的方法顺序允许后续成功推送排在先前已入队的删除之后，这可以用于验证清理结果。不能只看到删除请求被接受，就认定所有名称相似的序列都已经被处理，尤其不能把分组键误当成标签子集查询。

抓取时间不等于最近成功时间

网关通过 push_time_seconds 导出某组最近成功推送的时间。读取指标端点不会推进这个值。Prometheus 为采集样本赋予抓取时间戳，所以刚刚抓到的样本仍可能描述很久以前的任务结果。如果真正关心任务何时成功完成，应把最近成功时间作为独立的仪表值导出，并按任务计划检查其新鲜度。

不要给推送的指标样本附带显式样本时间戳，Pushgateway 会拒绝这种输入。把 Unix 时间戳作为仪表指标的数值是另一回事，可以正常使用。推送成功也不能证明业务成功或已经立即持久化：任务可以成功报告自己的失败，而没有配置持久化的网关在重启后可能丢失保留数据。各项完成语义应分别核对。

同一分组键还需要明确并发写入责任。两个运行可能互相覆盖，较早开始但延迟完成的任务，也可能在较新任务之后推送。HTTP 接口不会替业务建立运行先后关系。应协调重叠任务，或在合适的记录中保留完成身份；不能只凭最后抵达网关，就断定它代表最新一轮。稳定键控制基数，不自动解决写入顺序。

坏掉的样子

任务失败或被停用之后，旧的成功指标可能一直存在。只检查序列是否存在的告警，就会漏掉没有发生的新执行。应把最近成功值与预期调度比较，并让任务移除与分组清理同步。若分组标签不断改变，新旧运行还可能永久并列显示，给面板制造重复任务或持续健康的错觉，而实际已经没有新的成功结果。

本来想发布完整快照，却使用 POST，可能保留本次任务已不再输出的指标；只准备更新一个指标，却使用 PUT，又可能删除其他面板仍需要的结果。应明确哪个组件拥有整个分组，以及它使用哪种方法。不存在能够代替这些 HTTP 语义的 --replace 选项，不能把一个未经核实的命令参数写进操作流程。

快速验证

保存为 pushgateway.py 后运行 python3 pushgateway.py。需要 Docker 与 Pushgateway 1.11.1 镜像，未缓存时可能下载。一次性服务器只通过容器回环地址接收请求，不发布宿主机端口，不挂载本地目录，退出清理也仅针对本次唯一名称的容器。实验数据是固定的示意批任务结果，不会接触真实任务。

import http.client
import io
import json
import subprocess
import time
import uuid

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")


port = 9091
script = r"""exec /bin/pushgateway --web.listen-address=127.0.0.1:9091
"""
try:
 subprocess.run(
 ["docker", "run", "-d", "--rm", "--name", name, "--network", "none",
 "--entrypoint", "/bin/sh", "prom/pushgateway:v1.11.1", "-c", script],
 check=True, capture_output=True, text=True, timeout=20,
 )
 eventually(lambda: request("GET", "/metrics")[0] == 200)
 group = "/metrics/job/nightly_sync/team/data"
 first = "# TYPE items_processed gauge\nitems_processed 7\n# TYPE last_success_unixtime gauge\nlast_success_unixtime 1234\n"
 assert request("PUT", group, first, "text/plain; version=0.0.4")[0] == 200
 def snapshot():
 status, body = request("GET", "/metrics")
 assert status == 200
 return {line.split("{", 1)[0]: float(line.rsplit(" ", 1)[1])
 for line in body.splitlines()
 if not line.startswith("#") and 'job="nightly_sync"' in line}
 def first_snapshot():
 data = snapshot()
 return data if data.get("items_processed") == 7 else None
 initial = eventually(first_snapshot)
 assert initial["last_success_unixtime"] == 1234
 time.sleep(0.2)
 assert snapshot()["push_time_seconds"] == initial["push_time_seconds"]
 partial = "# TYPE items_processed gauge\nitems_processed 9\n"
 assert request("POST", group, partial, "text/plain; version=0.0.4")[0] == 200
 after_post = snapshot()
 assert after_post["items_processed"] == 9 and after_post["last_success_unixtime"] == 1234
 replacement = "# TYPE items_processed gauge\nitems_processed 11\n"
 assert request("PUT", group, replacement, "text/plain; version=0.0.4")[0] == 200
 after_put = snapshot()
 assert after_put["items_processed"] == 11 and "last_success_unixtime" not in after_put
 assert request("DELETE", "/metrics/job/nightly_sync")[0] == 202
 # A successful later POST orders the preceding queued deletion before this check.
 assert request("POST", group, "", "text/plain; version=0.0.4")[0] == 200
 assert snapshot()["items_processed"] == 11
 assert request("DELETE", group)[0] == 202
 eventually(lambda: not snapshot())
 print(json.dumps({"initial_items": 7, "post_items": 9, "put_items": 11,
 "post_preserved_other_metric": True, "put_removed_other_metric": True,
 "scrapes_did_not_refresh_push_time": True,
 "parent_group_delete_did_not_match": True, "group_deleted": True}, indent=2))
finally:
 subprocess.run(["docker", "rm", "-f", name],
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

断言显示，最初 PUT 后处理数量为七；POST 后变成九，同时保留独立的最近成功仪表值；再次 PUT 后变成十一，并移除另一指标。重复读取不会刷新推送时间。删除仅包含任务名的分组，不影响带团队标签的分组；删除完整分组键后，其指标才消失。实验验证网关接口行为，不验证任务调度、Prometheus 接入或持久恢复。

本轮没有修改此运行实验，也没有重新执行。文中的预期输出和此前记录的观察，与本轮执行证据分别保留，不能据此声称真实集成已经再次通过。

来源

Prometheus: when to use the Pushgateway，服务级批任务的有限适用场景与保留序列，已核验 2026-10-15。
Pushgateway 1.11.1: README，写入方法、删除、分组键与推送时间，已核验 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。

Prometheus 序列失效与告警等待是不同机制

Wed, 03 Feb 2027 00:00:00 +0000

指标缺失不等于数值为零。Prometheus 会区分具有近期值的序列、已经标记失效的序列，以及找不到可用样本的选择器；告警又在查询结果之上使用自己的评估和等待规则。如果把这些机制统称为一个宽限时间，就可能漏掉被移除的目标，或者没有弄清到底缺少什么数据便宣布服务故障。准确的缺失告警首先需要准确描述观测对象。

失效标记不是统一的五分钟计时器

即时选择器通常使用回看范围内最新的合格样本，默认回看范围是五分钟。失效标记会告诉引擎：在标记之后，不再让这条序列出现在即时选择结果中。它不要求旧值再保留五分钟。历史样本仍然存在于存储中，也可能继续参与范围查询；因此，即时查询已经看不到某条序列，与历史窗口里完全没有样本，并不是同一件事。

具体采集路径会影响行为。导出器不再输出某个指标、目标从服务发现消失，以及导出器自己提供样本时间戳，不一定遵循相同的时间过程。显式时间戳和失效跟踪配置也会改变结果。在依据抓取周期推测消失时刻之前，应先确认导出器使用哪条路径。可配置的回看范围本质上是查询选择规则，不是能够统一判定所有服务故障的计时器。

先确定要询问哪一种缺失

absent(selector) 在选择器没有任何元素时返回一；只要仍有匹配数据，即使数值为零，也返回空向量。absent_over_time(selector[3m]) 则询问所选三分钟范围内是否存在样本。失效标记之前的真实样本，可能继续留在这个范围内，使范围缺失表达式保持为空，直到该样本移出窗口。这不是查询互相矛盾，而是问题的时间范围不同。

告警规则的 for 又是一层机制：相关标签集必须在连续的评估中持续由表达式返回，经过等待时长后才进入触发状态。它不会配置序列失效，也不会延长查询回看范围。把三分钟缺失窗口再配上额外等待时间，会进一步延后通知，评估节奏和采集时机也影响最终延迟。选择这些参数时，应从允许的发现时间反推，而不是只把它们当作降噪旋钮。

坏掉的样子

absent(up{job="api"}) 不是抓取失败告警。若已配置目标仍存在，只是 up=0，选择器仍有元素，缺失条件便不成立。与零比较才能检查这个场景。但如果目标彻底从发现清单消失，只检查零又可能在其序列消失之后漏报。对目标是否应当存在有要求时，需要另行监测预期成员关系，不能让一个表达式混合承担所有职责。

宽泛的选择器也不会自动列举所有缺少的成员。一个副本仍有数据时，对整个任务求 absent 仍为空，即使其他几个预期副本已消失。可以匹配明确已知的身份，或者将观测序列与权威清单比较。标签被改名同样可能使旧匹配条件看起来像发生故障，而进程其实正在以新身份正常工作，所以规则与标签变更需要一起审阅。

快速验证

保存为 stale.py，运行 python3 stale.py。环境需要已经安装的 promtool，可以从 PATH 找到，或用 PROMTOOL 指定其可执行文件路径。本轮使用 Python 3.12.14 与 promtool 3.14.0。真实查询引擎在临时目录中评估合成样本，不启动服务器、监听端口或容器，也不联系外部服务。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

# Uses a real, installed promtool; no server or Docker runtime is started.
promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if not promtool:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")

tests = r"""evaluation_interval: 1m
rule_files: [rules.yml]
tests:
 - interval: 1m
 input_series:
 - series: "up{job=\"api\",instance=\"gone\"}"
 values: "1 0 0 0 0"
 - series: "service_events_total{job=\"api\",instance=\"gone\"}"
 values: "10 stale _ _ _"
 - series: "service_events_total{job=\"api\",instance=\"zero\"}"
 values: "0 0 0 0 0"
 promql_expr_test:
 - expr: "service_events_total{job=\"api\",instance=\"gone\"}"
 eval_time: 1m
 exp_samples: []
 - expr: "up{job=\"api\",instance=\"gone\"}"
 eval_time: 1m
 exp_samples:
 - labels: "{__name__=\"up\",job=\"api\",instance=\"gone\"}"
 value: 0
 - expr: "absent(service_events_total{job=\"api\",instance=\"gone\"})"
 eval_time: 1m
 exp_samples:
 - labels: "{job=\"api\",instance=\"gone\"}"
 value: 1
 - expr: "absent_over_time(service_events_total{job=\"api\",instance=\"gone\"}[3m])"
 eval_time: 2m
 exp_samples: []
 - expr: "absent_over_time(service_events_total{job=\"api\",instance=\"gone\"}[3m])"
 eval_time: 4m
 exp_samples:
 - labels: "{job=\"api\",instance=\"gone\"}"
 value: 1
 - expr: "absent(service_events_total{job=\"api\",instance=\"zero\"})"
 eval_time: 4m
 exp_samples: []
 - expr: "absent(up{job=\"api\"})"
 eval_time: 4m
 exp_samples: []
 - expr: 'absent_over_time(service_events_total{job="api",instance="gone"}[3m])'
 eval_time: 3m
 exp_samples:
 - labels: '{job="api",instance="gone"}'
 value: 1
 - expr: 'ALERTS{alertname="BusinessMetricMissing",alertstate="pending"}'
 eval_time: 3m
 exp_samples:
 - labels: '{__name__="ALERTS",alertname="BusinessMetricMissing",alertstate="pending",job="api",instance="gone"}'
 value: 1
 alert_rule_test:
 - eval_time: 4m
 alertname: BusinessMetricMissing
 exp_alerts: []
 - eval_time: 5m
 alertname: BusinessMetricMissing
 exp_alerts:
 - exp_labels: {job: api, instance: gone}
 exp_annotations: {}
"""
rules = r"""groups:
 - name: absence
 rules:
 - alert: BusinessMetricMissing
 expr: absent_over_time(service_events_total{job="api",instance="gone"}[3m])
 for: 2m
"""

with TemporaryDirectory(prefix="prometheus-query-check-") as directory:
 root = Path(directory)
 (root / "tests.yml").write_text(tests, encoding="utf-8")
 if rules:
 (root / "rules.yml").write_text(rules, encoding="utf-8")
 result = subprocess.run([promtool, "test", "rules", "tests.yml"],
 cwd=root, text=True, capture_output=True, timeout=45)
 print(result.stdout, end="")
 if result.returncode:
 print(result.stderr, end="")
 raise SystemExit(result.returncode)

成功时输出 SUCCESS。第一分钟，已经标记失效的业务序列不再被即时选择，但单独提供的 up 序列仍存在，数值为零；即时 absent 返回一。第二分钟，三分钟范围仍包含最初的业务样本，因此 absent_over_time 不返回元素；到了第三分钟，左开边界就已经排除最初样本，因此返回一，第四分钟仍返回一。程序分别断言每种结果，而不是只检查命令退出。

持续导出零值的业务序列从来不算缺失，整个任务的 up 选择器也不算缺失。这些断言把没有值与值表示失败区分开来，没有把两者都强行补零。临时测试文件会在退出时清理。新增规则在第三分钟进入等待，第四分钟仍未触发，第五分钟才经过独立的两分钟 for 时长而触发。断言同时检查等待状态和触发时点；真实抓取、目标移除及通知送达仍是独立的集成测试，不能从合成时间线推断实际发现延迟。

来源

Prometheus: querying basics，即时选择器、回看范围与失效标记，已核验 2026-10-15。
Prometheus: query functions，即时缺失与范围缺失函数的行为，已核验 2026-10-15。
Prometheus: unit testing rules，缺失样本和失效样本的测试记法，已核验 2026-10-15。
Prometheus：告警规则，等待时长与合成 ALERTS 序列，已核验 2026-10-15。

Prometheus 直方图保留分桶后的分布信息

Wed, 06 Jan 2027 00:00:00 +0000

延迟平均值可能隐藏一部分特别慢的请求。直方图通过记录落入不同桶的观测数量，保留更多分布信息，但仍然丢弃桶内部的细节。Prometheus 可以从这些计数估计分位数，无需保存每次请求的原始耗时。估计结果取决于桶边界与聚合方式，不能称为完整恢复了原始延迟分布，也不能因为输出包含小数就认为测量具有同样精度。

经典直方图由多条相关序列组成

经典直方图导出累计的 _bucket 计数器，以及 _count 与 _sum。le 标签表示每个桶包含的上界。一点五秒的观测会增加两秒桶和所有更大的桶，所以这些桶不是互不重叠的区间，不能直接相加得到总请求数。正无穷桶包含全部观测，与总计数对应。一个经典直方图因此不是一条可以单独理解的普通序列。

对于非负延迟观测，分别对总和与总计数应用 rate，可以得到每秒累计的耗时和每秒观测数量；两者相除就是以秒为单位的平均延迟。桶速率则描述选定时间范围内的分布。应该先对各条计数器求速率，再合并实例，这样各序列已经观测到的重置能够独立处理，不会在求和时被另一实例的增长掩盖。

先合并桶，再估计总体分位数

需要整个服务的一个分位数时，应在保留 le 的前提下合并桶速率，再调用 histogram_quantile。查询需要区分服务等维度时，也应保留相应标签。参与合并的桶边界要兼容，事件定义也要一致。如果先把 le 消掉，就丢失了经典分位数函数所需的桶身份，留下的数值无法继续表达累计分布。

不要平均各实例的分位数。分位数是分布中的位置，不是可相加的计数，即使各实例请求量完全相同，平均分位数也未必等于总体分位数。合并桶曲线可以具有与任何单个实例都不同的形状。如果问题是两秒以内完成的请求比例，恰好以两秒为边界的桶除以总计数，就可以直接回答这个阈值问题，不必绕到分位数再反推。

摘要指标可以导出客户端预先计算的分位数，这些数值也不能通过求和或平均合成总体分位数。不过，只要事件定义一致，它的总计数与总和仍可用于计算合并平均值。选择指标类型时，应从所需聚合能力出发，而不是仅看面板希望直接显示什么字段。

坏掉的样子

关注的分位数落在很宽的桶内时，输出容易显得比实际测量更精确。经典分位数计算会在选中的桶内插值，却不知道每个观测在桶内的真实位置。应围绕服务目标设置有用的边界，并在升级前审阅桶定义，避免滚动发布期间不同实例混用不兼容方案。事后加密桶边界也不会恢复旧观测已经丢失的细节。

桶或导出器缺失，与没有观测不同。面板上看似改善的分位数，也可能只是最慢实例的指标丢了。解释改善之前，应检查抓取完整性、参与计算的序列和样本数量。观测太稀疏或完全缺失时，分位数可能没有可用含义；把这种结果替换成零延迟，会制造虚假的成功信号，而不是补全测量。

快速验证

保存为 histogram-query.py，运行 python3 histogram-query.py。环境需要已经安装的 promtool，可以从 PATH 找到，或用 PROMTOOL 指定其可执行文件路径。本轮使用 Python 3.12.14 与 promtool 3.14.0。真实查询引擎在临时目录中评估合成样本，不启动服务器、监听端口或容器，也不联系外部服务。

from pathlib import Path
from tempfile import TemporaryDirectory
import os
import shutil
import subprocess

# Uses a real, installed promtool; no server or Docker runtime is started.
promtool = shutil.which(os.environ.get("PROMTOOL", "promtool"))
if not promtool:
 raise SystemExit("Set PROMTOOL to an installed promtool executable")

tests = r"""evaluation_interval: 1m
tests:
 - interval: 1m
 input_series:
 - series: "api_duration_seconds_bucket{instance=\"fast\",le=\"1\"}"
 values: "0+95x5"
 - series: "api_duration_seconds_bucket{instance=\"fast\",le=\"2\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_bucket{instance=\"fast\",le=\"5\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_bucket{instance=\"fast\",le=\"+Inf\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_count{instance=\"fast\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_sum{instance=\"fast\"}"
 values: "0+17x5"
 - series: "api_duration_seconds_bucket{instance=\"slow\",le=\"1\"}"
 values: "0+0x5"
 - series: "api_duration_seconds_bucket{instance=\"slow\",le=\"2\"}"
 values: "0+0x5"
 - series: "api_duration_seconds_bucket{instance=\"slow\",le=\"5\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_bucket{instance=\"slow\",le=\"+Inf\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_count{instance=\"slow\"}"
 values: "0+100x5"
 - series: "api_duration_seconds_sum{instance=\"slow\"}"
 values: "0+400x5"
 - series: 'tail_duration_seconds_bucket{le="1"}'
 values: "0+0x5"
 - series: 'tail_duration_seconds_bucket{le="5"}'
 values: "0+90x5"
 - series: 'tail_duration_seconds_bucket{le="+Inf"}'
 values: "0+100x5"
 promql_expr_test:
 - expr: "abs(histogram_quantile(0.99, sum by (le) (rate(api_duration_seconds_bucket[2m]))) - 4.94) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "abs(avg(histogram_quantile(0.99, rate(api_duration_seconds_bucket[2m]))) - 3.385) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: "sum(rate(api_duration_seconds_bucket{le=\"2\"}[2m])) / sum(rate(api_duration_seconds_count[2m]))"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 0.5
 - expr: "abs(sum(rate(api_duration_seconds_sum[2m])) / sum(rate(api_duration_seconds_count[2m])) - 2.085) < bool 1e-12"
 eval_time: 5m
 exp_samples:
 - labels: "{}"
 value: 1
 - expr: 'histogram_quantile(0.99, rate(tail_duration_seconds_bucket[2m]))'
 eval_time: 5m
 exp_samples:
 - labels: '{}'
 value: 5
"""
rules = r""""""

with TemporaryDirectory(prefix="prometheus-query-check-") as directory:
 root = Path(directory)
 (root / "tests.yml").write_text(tests, encoding="utf-8")
 if rules:
 (root / "rules.yml").write_text(rules, encoding="utf-8")
 result = subprocess.run([promtool, "test", "rules", "tests.yml"],
 cwd=root, text=True, capture_output=True, timeout=45)
 print(result.stdout, end="")
 if result.returncode:
 print(result.stderr, end="")
 raise SystemExit(result.returncode)

成功时输出 SUCCESS。正确合并后的百分之九十九分位数估计是四点九四秒；分别计算两个实例后再平均，得到三点三八五秒，并不是总体结果。满足两秒阈值的观测占一半，合并平均延迟为二点零八五秒。断言对浮点结果采用很小的数值容差，避免要求十进制小数必须具有完全相同的二进制表示。

实验验证查询算术与聚合，不验证真实应用的埋点，也不能还原每个桶内部的分布。执行结束后会删除临时测试文件。当前 Prometheus 指南也讨论原生直方图，它使用不同的桶编码，在仪表化和存储链路支持时能够简化查询。本例明确使用经典直方图，所以需要保留 le、正确合并计数器速率，并把输出分位数称为估计值。

第二个直方图把百分之十的观测放在最大有限边界五秒之外，但其百分之九十九分位数仍返回五。经典分位数落入正无穷桶时，函数返回前一个有限桶的上界。这个数不是测得的最大值，也不证明百分之九十九的请求在五秒内完成。新增断言把这个显示陷阱直接暴露出来，提醒读者观察尾部是否超出当前桶范围。

来源

Prometheus: histograms and summaries，分桶观测、聚合与指标类型选择，已核验 2026-10-15。
Prometheus: query functions，经典直方图分位数插值与速率计算顺序，已核验 2026-10-15。
Prometheus: unit testing rules，执行并核对查询预期值，已核验 2026-10-15。

把单位写进指标名里

Fri, 30 Oct 2026 00:00:00 +0000

名为 request_duration 的指标会让读者猜测，二百五十究竟表示秒、毫秒还是别的量。面向 Prometheus 的名称，例如 http_request_duration_seconds，能够把单位约定带入查询、记录规则与告警配置。但这个约定必须由正确实现支撑：给毫秒数据的名字加上秒后缀，不会自动改变数值大小，反而可能让监控产生一千倍的误差。名称提供线索，转换逻辑才决定数据是否可信。

在明确的边界完成换算

每个指标族应只表示一种量和一种单位。Prometheus 建议使用秒、字节等基础单位，并在适用时把单位写为后缀。持续时间与绝对时间戳都可以用秒表示，却不是同一种量，因此不能因为名字都含秒，就把上次成功的时间戳与一次请求的耗时直接相加。帮助文本应写明测量对象、开始结束边界以及含义，让简短名称背后仍有明确的契约。

如果底层库输出毫秒，应在观测或导出边界转换一次，并保留足够精度，避免把很短的耗时截断为零。仪表盘可以按基础单位配置显示，让零点二五秒自动显示为二百五十毫秒，这只改变呈现方式，不改变存储样本。不能仅因为坐标轴显示毫秒，就在记录规则中再做一次换算，否则查询和图表会在不同环节重复缩放。

单位与类型回答不同问题

累计传输字节数通常使用字节加总量后缀，当前内存占用仪表则只使用字节后缀。两者单位相同，但只有前者表示不断累积的工作量，适合计算计数器速率。请求次数按惯例使用总量后缀，无须编造一个物理单位。直方图的桶、总和与计数，还会在耗时指标族名称后加入各自的组件后缀，因此阅读名称时也要识别指标族与导出组件之间的关系。

比例通常表示零到一之间的分数，而百分数使用另一种数值尺度，面板应明确自己期待哪种输入。计数器可以在进程重启时归零，Prometheus 的计数器速率函数会根据观测序列中的下降处理重置，并不要求额外存在创建时间序列。应先分别计算独立计数器的速率，再执行聚合，让各自的重置仍能被识别；不要先把多个实例的累计值混成一条看似连续的曲线。

坏掉的样子

名字正确的指标仍然可能承载错误数值。如果同一个标识下混入秒和毫秒，历史数据已经被污染，修改帮助文字或补一个说明标签不能修复旧样本。单位迁移应被视为契约变化，生产端、查询、告警和仪表盘需要一起核对，历史区间的比较也必须说明边界。旧序列含义不兼容时，可以采用新的指标标识，避免新旧数值被误当成同一种量连续使用。

名称后缀也不会强制执行计数器语义。一个普通运行过程中可以升降的仪表，即使名字带总量后缀，也不适合按累计计数器解释。反过来，已经得到每秒速率后再除以时间窗口，会制造另一种量。这些是维度和测量语义的问题，不能只靠显示格式解决。其他遥测体系可能把单位放在元数据中，应遵循已定义的导出映射，而不是机械重命名所有上游仪器。

快速验证

把代码保存为 units.py，使用 Python 3 执行。程序转换三条人为构造的延迟观测，并输出带帮助文字和类型声明的 Prometheus 文本格式。十进制定点运算使毫秒到秒的换算清楚可见；阈值比较则展示，仅仅改名、却不转换数据的生产端，为什么不能和正确的生产端共用同一条延迟规则。

from decimal import Decimal

latency_ms = [Decimal('120'), Decimal('250'), Decimal('630')]
latency_seconds = [value / Decimal('1000') for value in latency_ms]
threshold_seconds = Decimal('0.300')
correct_good = sum(value <= threshold_seconds for value in latency_seconds)
rename_only_good = sum(value <= threshold_seconds for value in latency_ms)
transferred_bytes = 1024 * 1024
used_ratio = Decimal('25') / Decimal('100')

assert correct_good == 2 and rename_only_good == 0
assert sum(latency_seconds) == Decimal('1.000')
assert used_ratio == Decimal('0.25')
print(f"# within 0.300s: converted={correct_good}/3, rename_only={rename_only_good}/3")
print('# HELP demo_last_request_duration_seconds Duration of the most recent completed request.')
print('# TYPE demo_last_request_duration_seconds gauge')
print(f'demo_last_request_duration_seconds {latency_seconds[-1]:.3f}')
print('# HELP demo_transferred_bytes_total Bytes transferred since this process started.')
print('# TYPE demo_transferred_bytes_total counter')
print(f'demo_transferred_bytes_total {transferred_bytes}')
print('# HELP demo_capacity_used_ratio Fraction of configured capacity currently used.')
print('# TYPE demo_capacity_used_ratio gauge')
print(f'demo_capacity_used_ratio {used_ratio}')

首行注释说明，转换后有三分之二的观测不超过零点三秒，而把毫秒数值直接当成秒时，三条都无法满足阈值。导出的最后请求耗时为零点六三秒，累计字节数为一百零四万八千五百七十六，容量使用比例为零点二五，在百分比界面上对应百分之二十五。三个数分别对应持续时间、累计大小与无量纲比例，不能因为都能画成曲线就混用。

本次完整 Python 输出已通过 promtool 3.14.0 的 promtool check metrics 校验。这个结果说明示例的文本格式和命名检查通过，却不能推断真实埋点确实测到了承诺的业务量。对生产指标应选取一个数值已知的输入，沿采集、导出、查询和显示逐步核对，确认单位只转换一次、阈值仍使用相同尺度后，再依赖它进行判断。

来源

Prometheus: Metric and Label Naming，基础单位、后缀与 Prometheus 边界的命名约定，已核验 2026-09-13。
Prometheus: Data Model，指标标识与标签，已核验 2026-09-13。
Prometheus: Query Functions，计数器速率与重置处理，已核验 2026-09-13。

Prometheus · XB 现场笔记

注解解释告警现场，同时保留稳定身份

区分身份与当前说明

一组告警未必拥有共同摘要

坏掉的样子

快速验证

来源

记录规则保存按周期计算的查询结果

三个时钟共同影响页面上的值

预计算也改变了保留的数据

坏掉的样子

快速验证

来源

高基数标签在查询之前就增加存储序列

统计实际组合，而不是孤立取值

查询少几行，不代表少存几行

使用正确范围的清单诊断增长

坏掉的样子

快速验证

来源

Prometheus rate 估计计数器每秒的增长速度

采样决定能够推断多少事实

选择的范围也是指标含义的一部分

坏掉的样子

快速验证

来源

Alertmanager 通过标签匹配树选择告警接收器

既要看匹配，也要看何时停止

责任归属依赖稳定的标签契约

坏掉的样子

快速验证

来源

Prometheus 规则先跟踪告警状态，再交给通知链路

表达式返回元素就会激活告警候选项

等待时长通过评估时刻观察

坏掉的样子

快速验证

延伸阅读

来源

记录规则应保留比例的分子和分母

百分比必须对应明确的总体

按顺序建立规则依赖

坏掉的样子

快速验证

来源

Prometheus 主动抓取指标，并记录抓取结果

一个任务包含多个独立抓取的实例

准确理解系统生成的指标

坏掉的样子

快速验证

让结果指向具体排查动作

来源

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

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

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

坏掉的样子

快速验证

来源

Alertmanager 分组组织告警，静默抑制通知

分组键决定哪些细节放在一起

初次等待、组内变化和重复提醒使用不同计时

坏掉的样子

快速验证

来源

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

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

序列已有的标签优先

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

坏掉的样子

快速验证

来源

Pushgateway 保留批任务指标，直到生命周期被主动处理

为稳定的批任务结果建立身份

替换范围由 HTTP 方法决定

抓取时间不等于最近成功时间

坏掉的样子

快速验证

来源

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

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