监控 · XB 现场笔记

iotop 能看出是哪个进程在烧磁盘

Wed, 15 Mar 2028 00:00:00 +0000

磁盘突然飙升却找不到明显的写入者时，iotop 把吞吐直接指回那个在捣乱的进程。系统级工具只给症状——await 高、util 打满——不给嫌疑人：五十个进程共享磁盘，平均值平等地怪每一个。终结调查的永远是按进程的问题——谁、多少、何时开始——iotop 从内核计数器实时回答，应用藏都没处藏。

把它放在系统级视图旁边，而不是代替。iostat 或 vmstat 说磁盘是瓶颈，iotop 点名是谁造成的。两者合起来把存储悬案压成两条命令：确认资源，锁定消费者。

逐个进程的计数器

iotop 从内核读每个进程的 IO，于是实时读写速率能对应到一个 pid，而不是一个说不清来源的负载均值。加 -o 只显示真正在做 IO 的进程，一眼看清。默认视图读写分开，还带 swap-in 百分比，把真吃磁盘的和仅仅在场的分开——DISK READ 高、写零的是在扫，写高的在产； throttle、迁移还是杀，取决于这个区分。

注意计数器量的到底是什么：穿过 IO 层的按进程字节，含还没落盘的缓冲写。进程写速率巨大、磁盘看着却闲（页缓存吸收），或速率平平、磁盘打满（大量小同步写），都可能。iotop 跟设备 util 一起读：进程侧定罪加设备侧饱和才是完整画面，任一半单独都误导。

看到谁在扫盘

按带宽排序，那个罪魁就现形了，无论是日志囤积、索引器还是失控备份。跟住这个 pid，就能定位到确切的进程（往往还有文件），再动手不迟。惯犯名单：debug 级别没轮转的日志、排在高峰的重建索引、同盘读写备份、坏镜像上循环解包的容器层。修法各不同——轮转、改期、分开、清理——杀进程治标，病因明天定时再来。

动手前把 pid 解析到完整上下文：命令行、工作目录、lsof 看开文件、父进程。一个烧写的 java 进程背后可能是一个 PID 命名空间里的十个应用；修要修对那一个。先定罪后动手——每个以遗憾收场的存储 war story 都跳过了第一步。

先看再动

iotop 只观察、不改变任何东西，所以你可以在决定节制、迁移或停掉之前先把元凶查清楚。再配 strace 或 lsof 打到这个 pid，把文件和系统调用一并钉死。组合是决定性的：iotop 说 18412 进程写 400MB/s，lsof 说写进一个膨胀的日志文件，strace 显示 4KB 的 O_APPEND 写——诊断完毕；修法（日志级别、轮转、异步 appender）不言自明，不用开会争。

健康时录基线，故障时对比才有意义。平时某天 iotop -b -n 60 落文件五分钟，就是这台机器的"正常"数字：平时谁领跑、多少速率算寻常。没有它，每次 spike 都像史无前例；有了它，多数 incident 几秒归类：“又是 indexer，提前一小时”。把 iotop 批输出和系统监控同一时段的曲线放一起看，进程侧和设备侧互相印证，结论才站得住。单看任何一边，都可能把相关当因果。告警阈值按基线设，而不是拍脑袋，基线之外的 spike 才值得半夜起床。把 Top 写入者的变化趋势也画出来，渐变比突变更早暴露问题。

基线文件要标清楚采集条件：采集时段、业务负载水位、iotop 的采样间隔与累计方式，否则下次对比就是拿苹果比橙子。建议每周固定一个低峰窗口复采一次，覆盖掉业务自然增长带来的漂移；复采后把新旧两份排名并排 diff，只看名次变化超过三位的进程，逐个确认是业务上线还是异常冒头，再决定跟进还是放行。确认结论也要回写基线备注。

坏掉的样子

最经典的元故障是权限盲：没特权跑，iotop 进程细节全问号，别用户的进程直接不显示——而真凶恰跑在别用户下，隐形到底。一开始就带够特权（root 或对应 capabilities），不然工具开脱的恰是你看不见的进程。无特权 iotop “什么都没查到”，只代表你自己的进程没事。

第二种是突发 IO 的采样幻觉：一分钟暴力一秒的进程，5 秒平均看着无辜，1 秒平均看着有罪，反之亦然。数字和症状对不上就换 delay 档；“过去一小时谁伤的盘"问累计总量（-a）不问瞬时速率。聚合方式对，问题才对；默认聚合只答它自己假设的那个问题。

快速验证

非交互地抓谁在做 IO，带上下文：

iotop -b -n 5 -o -d 2 | head -n 30
pid=$(iotop -b -n 1 -o | awk 'NR>5 {print $1}' | head -n 1); ls -l /proc/$pid/exe; cat /proc/$pid/cmdline | tr '\0' ' '
iostat -x 1 3 | grep -E "Device|sd|nvme"

batch 抓排名不占终端，pid 解析点名头号写者的二进制，iostat 确认设备侧真打满。

来源

iotop 手册，iotop 官方参考，已核验 2026-06-01。
vmstat 手册，说明系统级 CPU 与 IO 等待报告，已核验 2026-09-05。

Grafana 变量必须与查询语言的语义一致

Wed, 23 Feb 2028 00:00:00 +0000

Grafana 仪表盘变量让同一组面板能够切换环境、服务或实例，而不必复制多份仪表盘。查询变量从数据源获得选项，自定义变量则可以维护一份有意固定的列表。这两种方式没有绝对优劣：当选项应跟随数据源发现结果变化时，可以使用查询变量；当选择范围就是一份较小且稳定的约定时，维护静态列表同样合理。变量是否合适，取决于它如何表达实际使用需求。

数据源执行查询之前，变量会先被代入查询表达式，所以变量格式本身属于查询正确性的一部分。Prometheus 多选场景应使用正则标签匹配，例如 environment=~"$environment"。Grafana 的 Prometheus 插值逻辑会把选中值处理为正则候选项，并执行所需转义。如果改用精确等号匹配，组合后的文本只会被当成一个标签值，并不会自动变成希望表达的多个环境选择。变量编辑器里的 label_values 是发现选项的辅助语法，不是可以直接复制到面板表达式中使用的 PromQL 函数。

检查最终送出的表达式

这里存在两层语法：正则表达式，以及包裹它的 PromQL 字符串。production.eu 中的点号应表示字面字符，不能成为同时匹配 productionXeu 的通配符。应让数据源按其约定完成插值；使用显式格式覆盖时，要检查真正发送出去的查询。raw 格式会绕过数据源格式化，并不是解决复杂变量值的通用办法。表面上省掉反斜线，可能只是把错误隐藏在返回的数字中。

全部选项也有明确语义。本例没有设置自定义的全部值，因此会展开经过筛选的可用选项。菜单只包含 production.eu 和 staging，全部选择就应覆盖这两个环境。如果把全部值改成点星号等自定义表达式，范围则可能扩大到后台正则允许匹配的其他标签。需要先决定这里的全部究竟指当前菜单中的值，还是更广的查询范围，再用刻意排除的数据验证这种决定。

坏掉的样子

查询变量不会保证永远新鲜，刷新设置决定了 Grafana 何时重新执行选项查询。选项依赖时间范围时，通常还需要随时间范围变化刷新。存在链式变量，也不保证每组上游选择都能找到下游组合；数据本来不存在时，结果完全可能为空。应当区分真实的空集合、已经陈旧的选择和查询错误，不能看到无数据提示，就直接把它解释为服务故障。

变量筛选不是权限控制。菜单里隐藏一个环境，并不会从数据源删除它，也不会阻止其他获准查询请求这些数据。访问边界需要在对应的 Grafana 配置与后台数据服务中落实。分享链接携带的同样只是选中状态，不是权限声明。多个环境通过重复的 var-environment 参数传递，不能随意发明一个逗号拼接的权限列表，再期望后台自动按访问规则理解它。

快速验证

保存代码为 grafana-variables.py，在准备好 Python 和 Docker 后，运行 python3 grafana-variables.py –serve。脚本在专用桥接网络中创建可删除的 Grafana 12.1.0 与 Prometheus 3.5.1 容器，仅通过本机回环地址暴露 Grafana，不挂载宿主机目录。打开输出的仪表盘地址，结束后按控制键加 C，脚本会删除两个容器及本次网络。不带服务参数运行时，只执行后台检查并立即清理。

import json
import secrets
import subprocess
import sys
import time
import uuid
from http.client import HTTPException
from threading import Event
from urllib.error import HTTPError, URLError
from urllib.parse import quote
from urllib.request import urlopen

prefix = "xbcatm-variable-" + uuid.uuid4().hex[:10]
network, prom, grafana = [prefix + suffix for suffix in ("-net", "-prom", "-grafana")]


def command(*args):
 try:
 result = subprocess.run(["docker", *args], capture_output=True, text=True, timeout=30)
 except subprocess.TimeoutExpired:
 raise RuntimeError("Docker " + args[0] + " timed out") from None
 if result.returncode:
 raise RuntimeError(result.stderr.strip())
 return result.stdout.strip()


def get(path):
 with urlopen(origin + path, timeout=5) as response:
 return json.load(response)


def eventually(check):
 for attempt in range(200):
 try:
 value = check()
 if value:
 return value
 except (HTTPError, URLError, TimeoutError, ConnectionError, HTTPException):
 pass
 time.sleep(0.1)
 raise AssertionError("Local lab did not become ready")


source = {"type": "prometheus", "uid": "lab_prom"}
dashboard = {
 "uid": "variable-lab", "title": "Variable escaping lab", "schemaVersion": 41,
 "version": 1, "timezone": "utc", "refresh": "", "time": {"from": "now-5m", "to": "now"},
 "templating": {"list": [{
 "name": "environment", "label": "Environment", "type": "query", "datasource": source,
 "query": {"query": "label_values(lab_active_workers, environment)", "refId": "VariableQuery"},
 "definition": "label_values(lab_active_workers, environment)",
 "regex": "/^(production[.]eu|staging)$/", "refresh": 1, "sort": 1,
 "multi": True, "includeAll": True, "allValue": "", "options": [],
 "current": {"text": ["production.eu"], "value": ["production.eu"], "selected": True},
 }]},
 "panels": [{
 "id": number, "title": title, "type": "stat", "datasource": source,
 "gridPos": {"h": 7, "w": 12, "x": (number - 1) * 12, "y": 0},
 "targets": [{"refId": "A", "expr": expression, "instant": True, "range": False}],
 "options": {"reduceOptions": {"calcs": ["lastNotNull"], "fields": "", "values": False}},
 "fieldConfig": {"defaults": {"decimals": 0}, "overrides": []},
 } for number, title, expression in (
 (1, "Selected workers", 'sum(lab_active_workers{environment=~"$environment"})'),
 (2, "Unescaped control", 'sum(lab_active_workers{environment=~"${environment:raw}"})'),
 )],
}
prom_script = """set -eu
mkdir -p /tmp/www
cat > /tmp/www/metrics.txt <<'METRICS'
# HELP lab_active_workers Synthetic active worker count.
# TYPE lab_active_workers gauge
lab_active_workers{environment="production.eu"} 10
lab_active_workers{environment="staging"} 2
lab_active_workers{environment="productionXeu"} 100
METRICS
cat > /tmp/prom.yml <<'CONFIG'
global:
 scrape_interval: 1s
scrape_configs:
 - job_name: lab
 metrics_path: /metrics.txt
 static_configs:
 - targets: ['127.0.0.1:8080']
CONFIG
/bin/httpd -f -p 127.0.0.1:8080 -h /tmp/www &
exec /bin/prometheus --config.file=/tmp/prom.yml --storage.tsdb.path=/tmp/data
"""
grafana_script = """set -eu
mkdir -p /tmp/data /tmp/provisioning/datasources /tmp/provisioning/dashboards /tmp/dashboards
mkdir -p /tmp/provisioning/plugins /tmp/provisioning/alerting
cat > /tmp/provisioning/datasources/lab.yml <<'DATASOURCE'
apiVersion: 1
datasources:
 - name: Lab Prometheus
 type: prometheus
 uid: lab_prom
 access: proxy
 url: http://metrics:9090
 isDefault: true
 jsonData:
 timeInterval: 1s
DATASOURCE
cat > /tmp/provisioning/dashboards/lab.yml <<'PROVIDER'
apiVersion: 1
providers:
 - name: lab
 type: file
 options:
 path: /tmp/dashboards
PROVIDER
cat > /tmp/dashboards/lab.json <<'DASHBOARD'
""" + json.dumps(dashboard) + """
DASHBOARD
exec /run.sh
"""
try:
 command("network", "create", network)
 command("run", "-d", "--rm", "--name", prom, "--network", network, "--network-alias", "metrics",
 "--entrypoint", "/bin/sh", "prom/prometheus:v3.5.1", "-c", prom_script)
 command("run", "-d", "--rm", "--name", grafana, "--network", network,
 "-p", "127.0.0.1::3000", "-e", "GF_PATHS_DATA=/tmp/data",
 "-e", "GF_PATHS_PROVISIONING=/tmp/provisioning",
 "-e", "GF_AUTH_ANONYMOUS_ENABLED=true", "-e", "GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer",
 "-e", "GF_AUTH_DISABLE_LOGIN_FORM=true", "-e", "GF_AUTH_BASIC_ENABLED=false",
 "-e", "GF_SECURITY_ADMIN_PASSWORD=" + secrets.token_urlsafe(24),
 "-e", "GF_ANALYTICS_REPORTING_ENABLED=false", "-e", "GF_ANALYTICS_CHECK_FOR_UPDATES=false",
 "-e", "GF_ANALYTICS_CHECK_FOR_PLUGIN_UPDATES=false", "-e", "GF_PLUGINS_PREINSTALL_DISABLED=true",
 "--entrypoint", "/bin/sh", "grafana/grafana:12.1.0", "-c", grafana_script)
 origin = "http://" + command("port", grafana, "3000/tcp").splitlines()[0]
 health = eventually(lambda: get("/api/health"))
 assert health["version"] == "12.1.0" and health["database"] == "ok"
 loaded = eventually(lambda: get("/api/dashboards/uid/variable-lab"))
 assert loaded["dashboard"]["templating"]["list"][0]["multi"] is True
 checks = {}
 for pattern, expected in ((r"production\\.eu", 10), (r"(production\\.eu|staging)", 12), ("production.eu", 110)):
 expression = 'sum(lab_active_workers{environment=~"' + pattern + '"})'
 result = eventually(lambda: get("/api/datasources/proxy/uid/lab_prom/api/v1/query?query=" +
 quote(expression, safe=""))["data"]["result"])
 value = float(result[0]["value"][1])
 assert value == expected, (expression, result)
 checks[expression] = value
 print(json.dumps({"app_url": origin + "/d/variable-lab/variable-escaping-lab",
 "grafana_version": health["version"], "query_checks": checks}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 for name in (grafana, prom):
 subprocess.run(["docker", "rm", "-f", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 subprocess.run(["docker", "network", "rm", network], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

合成数据中，production.eu 有十个工作实例，staging 有两个，productionXeu 有一百个。只选择 production.eu 时，正确面板应显示十，刻意不转义的对照面板则显示一百一十。选择两个可用环境后，再选择全部选项，正确面板都应显示十二。此时对照面板会为空，因为原样格式生成的是逗号连接文本，不能匹配预期的两个正则候选项。这两类失败都有真实数据作对照，而不是只检查表达式看起来是否合理。

本次使用 Chrome 152 操作实际 Grafana 页面，核对了这三种选择送出的查询及返回值，重复的 URL 参数也产生了同样的多选结果。这证明的是所配置变量对合成数据的插值行为，没有验证租户隔离，也没有测量动态发现下选项的新鲜度。修改仪表盘时，可以保留被排除的环境作为回归数据；当变量类型、格式覆盖、刷新策略或数据源改变，都应重新检查最终表达式，而不只检查下拉框还能否打开。

来源

Grafana variables，变量类型与仪表盘复用，已核验 2026-09-13。
Grafana Prometheus template variables，多选正则匹配与选项刷新行为，已核验 2026-09-13。
Grafana variable syntax，数据源插值与显式格式覆盖，已核验 2026-09-13。
Grafana dashboard URL variables，以重复 URL 参数表达多个选中值，已核验 2026-09-13。

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。

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。

基数是指标的预算

Wed, 21 Jul 2027 00:00:00 +0000

一个很短的指标名，背后可能对应大量存储与查询成本。Prometheus 使用指标名及完整标签集合标识一条时间序列，每出现一种新的实际标签组合，就形成另一条需要采集、建立索引、保留和查询的序列。基数预算关注的是，哪些区别值得付出这笔成本，以及服务增长时，这些区别的数量是否仍有明确上限。它不是单纯要求标签越少越好，而是要求每个维度都有可解释的用途。

统计真正出现的组合

标签维度会扩大可能的组合数，但只有每种组合都实际出现时，各维度取值数的乘积才等于真实数量。两条路由、两种方法、两类状态最多可以形成八种组合；如果每条路由只允许一种方法，导出的组合就可能更少。因此既要计算理论上界，也要核对实际输出，并把实例等采集目标标签纳入服务端最终接收的序列估计。

取值集合比标签名字是否好听更重要。标准化路由可以把同一类订单操作归在一起，而包含每个订单编号的原始路径会持续增加取值。请求编号、时间戳、用户标识以及任意查询字符串，都可能随着事件量增长。开发者把标签叫作路由，并不意味着它真的有界；还要检查真实流量中的值，尤其是错误路径、未匹配路径和很少出现的边界请求，避免正常测试掩盖高基数来源。

把指标表示方式一起算进去

对于每组实际标签，普通计数器通常产生一条主要序列，另外可能存在伴随指标。经典直方图则会展开成多个桶、总和与计数组件。如果有六条有限桶边界，再加正无穷桶、总和及计数，每组标签就对应九条核心序列。有些客户端还会导出创建时间序列，真实清单必须把它算上，不能将用于理解原理的简化公式当成完整埋点总量。

多个副本还会增加实例维度。采集间隔决定每条序列多久写入一个样本，保留期限决定历史数据保存多久，它们与不同序列的数量不是同一概念。不断变化的标识还会制造时序更替：生产端已经消失的短命组合，历史样本仍可能继续留在存储里。因此应分别观察活跃序列、新建速度、写入量、内存和查询表现，不能拿一个固定的“每条序列占多少字节”覆盖所有配置与工作负载。

坏掉的样子

看似方便排障的标签，可能把聚合指标变成逐请求事件仓库。只在仪表盘查询中去掉该标签，无法撤销已经发生的采集和保留成本。对每个标识计算哈希，也不会消除其唯一性；截断随机标识通常只是推迟增长问题，同时引入碰撞。如果业务真正需要的是分类统计，就应选择有明确上限的类别，而不是给无限集合换一种编码方式。

也不能为了降低成本，把识别用户影响所必需的区别全部压平。保留有意义且有界的结果或服务维度，把单次请求调查交给具有相应访问控制的日志和链路记录。如果在采集过程中删除标签，还要检查一次采集内是否出现重复的最终序列，以及诊断信息是否丢失。能够修改生产端时，应优先在那里修正，再验证新标签集合，并明确旧历史序列如何随保留策略逐步退出。

快速验证

保存为 cardinality.py 并使用 Python 3 执行。人为构造的事件把路由、方法和状态的每一种组合重复五十次。一种表示只保留这些有界维度，另一种再增加唯一的请求标识。计算假定二十个副本都导出相同的组合，并使用六条有限边界的经典直方图；这个前提在代码旁明确列出，便于读者核对乘法来源。

from itertools import product

routes = ["/orders/{order_id}", "/products/{product_id}"]
methods = ["GET", "POST"]
statuses = ["200", "500"]
events = list(product(routes, methods, statuses, range(50)))
bounded = {(route, method, status) for route, method, status, _ in events}
with_request_id = {(route, method, status, f"request-{i}")
 for i, (route, method, status, _) in enumerate(events)}

finite_buckets = 6
# Core classic-histogram series: finite buckets, +Inf, _sum, _count.
# Optional _created series are deliberately excluded from this calculation.
series_per_combination = finite_buckets + 3
replicas = 20
bounded_series = len(bounded) * series_per_combination * replicas
request_id_series = len(with_request_id) * series_per_combination * replicas

assert len(events) == 400 and len(bounded) == 8
assert len(with_request_id) == 400
assert bounded_series == 1440 and request_id_series == 72000
print(f"observed label sets: bounded={len(bounded)}, request_id={len(with_request_id)}")
print(f"core classic-histogram series: bounded={bounded_series}, request_id={request_id_series}")
print(f"multiplier={request_id_series // bounded_series}x")

四百条事件在有界表示下被聚合为八种组合，带请求标识时则保留四百种。扩展到二十个副本后，两者分别产生一千四百四十条与七万二千条核心直方图序列，相差五十倍。示例明确排除了可选创建时间序列和其他指标族，因此输出是给定假设下的序列数量模型，不是对 Prometheus 内存或磁盘占用进行过真实压测的结果。

这个对比说明，在埋点阶段聚合事件，就已经改变了后续系统的成本形态。批准新增标签前，应写明它回答的运维问题、预期最大取值集合、实际出现的组合，以及对各类指标表示的影响。上线后再用采集器和服务端数据验证这个估计，并在流量、错误路径或副本数量变化时持续复查，而不是等到查询变慢后才发现原本的假设已经失效。

来源

Prometheus: Data Model，时序标识与标签集合变化，已核验 2026-09-13。
Prometheus: Metric and Label Naming，有界标签与高基数维度，已核验 2026-09-13。
Prometheus: Instrumentation，基数成本与埋点取舍，已核验 2026-09-13。

看板是总结，不是放大镜

Sun, 18 Jul 2027 00:00:00 +0000

一张有用的看板，应该帮助读者决定接下来检查什么。它把大量观测归纳成少数几个问题：用户操作是否成功，影响发生在哪里，资源是否正在逼近限制。但归纳不能抹掉重要区别。全局成功率仍然很好看时，一个区域可能已经严重失败；面板空白也可能是遥测缺失，而不是服务处于安静且健康的状态。看板的价值在于减少重新推理的负担，同时保留做判断必需的上下文。

给页面安排清楚的阅读顺序

先展示服务结果和观测覆盖，再给出流量、延迟、错误以及有关资源的饱和信息。如果区域、操作类型或依赖的差异会改变下一步行动，就提供对应下钻入口。变更标记和诊断资料链接也应放在相关视图附近。曲线同时变化可以帮助选择调查方向，但仅凭发生时间接近，还不能证明某次部署或某个依赖导致了事故，仍需进一步验证真实链路。

每个面板应该回答明确的问题，但不要求只放一个指标。队列长度与配置上限使用相同单位，并列比较就很有意义；把不同单位放进复杂双轴图，则容易制造没有根据的视觉关系。应直接说明单位、聚合窗口、统计总体以及阈值含义，让读者不必凭记忆猜测坐标表示毫秒、秒、零到一比例还是百分数。含义清楚通常比增加面板数量更重要。

保留请求权重和观测覆盖

计算服务错误比例时，应使用相同窗口中的全部不良事件数除以全部符合条件的事件数。直接平均区域百分比，会让很安静的区域与繁忙区域获得相同权重，这已经换成另一种统计量，不是无关紧要的显示方式。即使全局值按请求正确加权，当小范围用户仍属于服务承诺的一部分时，也需要展示能定位影响的区域或操作细分。

新鲜度同样决定统计范围。应展示最近一次成功观测的时间，或者明确的覆盖信号，并约定何时把陈旧数据视为未知。业务看板选择的新鲜度阈值，与存储系统处理时序失效的机制是不同概念。把缺口一律补零，可能让已经不可用的采集器表现成完美错误率或空队列。缺失状态应被保留下来，并提供下一步排查采集链路或服务本身的方向。

坏掉的样子

自动缩放的纵轴可能把微小变化放大成重大事故，过宽的固定范围又可能掩盖真正越过阈值的变化。应根据运维问题选择刻度，让需要比较的面板保持一致。平均延迟还会藏起慢请求群体，需要合适的分布与观测数量作为补充；不能直接平均不同实例已经计算出的高分位数，再把它当成整个服务的尾部延迟。

外观漂亮的页面也可能只是一些互不相关的快照。时区、过滤条件、刷新频率和聚合窗口不同，会妨碍连贯比较。共享变量应有明确默认值和可见范围，尤其要让读者知道当前是否查看生产环境以及哪些区域。应拿区域故障、低流量和观测缺失来检查看板，如果三种场景都表现为绿色，就说明页面在压缩信息时丢掉了做决策所需的关键事实。

快速验证

将代码保存为 dashboard.py 并用 Python 3 执行。它基于一个完整六十秒窗口中的模拟计数，计算可以用于面板展示的值。两个区域有新鲜观测，另一个区域既缺少数值，最近观测时间也较旧。九十秒阈值是示例看板的业务规则，并不是 Prometheus 默认行为；验证这部分聚合逻辑不需要安装 Grafana，也不会操作任何现有仪表盘。

import json
from fractions import Fraction

# Counts cover the same completed 60-second interval.
rows = [
 {"region": "west", "requests": 9800, "errors": 0, "age_seconds": 10},
 {"region": "east", "requests": 200, "errors": 100, "age_seconds": 10},
 {"region": "south", "requests": None, "errors": None, "age_seconds": 240},
]
fresh = [r for r in rows if r["age_seconds"] <= 90
 and r["requests"] is not None and r["errors"] is not None]
missing = [r["region"] for r in rows if r not in fresh]
requests = sum(r["requests"] for r in fresh)
errors = sum(r["errors"] for r in fresh)
regional = {r["region"]: Fraction(r["errors"], r["requests"]) for r in fresh}
known_ratio = Fraction(errors, requests)
unweighted = sum(regional.values()) / len(regional)

assert known_ratio == Fraction(1, 100)
assert regional["east"] == Fraction(1, 2) and unweighted == Fraction(1, 4)
assert missing == ["south"]
print(json.dumps({
 "coverage": "incomplete",
 "fresh_requests_per_second": round(requests / 60, 3),
 "fresh_error_percent": float(known_ratio * 100),
 "regional_error_percent": {k: float(v * 100) for k, v in regional.items()},
 "wrong_unweighted_percent": float(unweighted * 100),
 "unknown_regions": missing,
}, indent=2))

新鲜观测合计一万次请求、一百次错误，对应每秒约一百六十六点六六七次请求，以及按请求加权后的百分之一错误率。然而流量较小的东部区域有一半请求失败。若直接平均两个区域的百分比，会错误地把合并请求错误比例写成百分之二十五。正确方式是让百分之一的总体值与区域细分共同出现，而不是挑选某一个数字来遮住另一个事实。

输出同时明确标记覆盖不完整，并把南部区域列为未知，没有凭空把它的请求数和错误数填写成零。这个实验核对的是面板背后的算术和缺失数据含义，不能替代对真实查询与页面的验证。把相同定义带入实际看板后，还应使用已知事故和遥测中断案例复查，确认读者看到的统计范围、状态与下一步行动仍然一致。

来源

Grafana: Dashboard Best Practices，目标、明确问题与连贯的阅读顺序，已核验 2026-09-13。
Google SRE: Monitoring Distributed Systems，以服务为中心的看板与信号，已核验 2026-09-13。
Prometheus: Metric and Label Naming，单位与有意义的聚合，已核验 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。

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。

健康的黄金信号

Sun, 29 Nov 2026 00:00:00 +0000

延迟、流量、错误与饱和度，是判断服务能否满足用户需求的四个互补角度。它们提供的是一组起始问题，并不是四个放到任何系统里都能自动证明健康的通用计数器。是否有用，取决于在哪里测量、描述哪些工作、采用什么时间窗口，以及各项统计如何对应。响应很快也可能意味着业务操作失败，因此不能看到延迟下降就直接宣布用户体验改善。

区分用户体验与工作需求

延迟描述一项工作在指定边界内花了多长时间。成功操作与失败操作应该分开观察，避免立即返回的错误让总体分布显得更健康。尾部信息很有价值，但必须同时保留观测数量；很少的样本即使算出了高分位数，也不能证明已经稳定掌握稀有行为。客户端延迟与服务器内部处理时间覆盖的链路不同，比较它们之前应先说明各自包含和遗漏的阶段。

流量描述需求或已经完成的工作，应采用请求每秒、字节每秒等合适单位，并明确统计的是到达、完成还是重试。队列卡住时，完成速率可以下降，但外部请求需求仍然持续增加。并发请求数则是数量，不是请求速率；它可以作为补充信息，却不能直接替换流量面板中的速率。批处理系统也应选择适合自身任务的工作单位，而不是机械套用接口请求数。

说明失败条件与资源压力

错误描述未达到承诺结果的工作。状态码失败是一种信号，但正常响应中包含错误业务数据，也可能违反服务契约。应明确哪些结果、哪些延迟违规进入指标，并使用相同统计范围的分母。除了比例，还应展示实际数量，使安静时段的一次错误与高峰时段影响大量用户的事故不会因为百分比相似而被混淆。

饱和度描述受约束资源距离可用上限有多近。处理器、内存、连接池、工作线程占用和队列等待时间，可以揭示不同的瓶颈。线程池全部忙碌不一定意味着不健康，但如果队列持续增长、最老任务不断等待，就能看出占用率为何值得关注。某一时刻的快照并不是整段时间的平均值，而很低的平均值也可能藏住短暂过载。容量阈值需要结合工作负载与实测，不能只在图上画一条没有依据的红线。

坏掉的样子

混用统计总体会制造难以解释的故事，例如延迟来自应用成功请求，错误来自入口代理，流量却来自另一个区域。它们可以独立变化，所以关联之前必须写明边界与过滤条件。快速拒绝请求可以改善全请求平均延迟，同时使错误率上升；只统计已经完成的请求，还会遗漏尚未结束的等待，让用户正在经历的停顿从延迟和吞吐图中同时消失。

四个信号中的任何一个都不能独立证明根因。处理器空闲时，数据库连接池可能已经耗尽；队列增长既可能源于更多需求，也可能因为下游变慢。应利用信号选择下一步排查方向，再查看链路、日志、依赖和变更证据。告警应针对可采取行动的用户影响或即将耗尽的资源，不能把任何单次仪表波动都等同于需要立刻叫醒值班人员的事故。

快速验证

保存为 golden.py 后使用 Python 3 执行。实验包含一个十秒窗口内的人造已完成请求，以及另行标注的窗口结束时线程与队列快照，用于核对聚合与解读。它没有向真实服务施压，也没有测量当前服务器；分位数直接来自原始样本的最近秩计算，与利用直方图桶进行插值估计的方式不同。

from math import ceil
from statistics import mean

# Synthetic completed requests in one 10-second observation interval.
records = [(True, 0.05)] * 90 + [(True, 0.8)] * 5 + [(False, 0.005)] * 5
success = sorted(duration for ok, duration in records if ok)
failure = [duration for ok, duration in records if not ok]
p99_success = success[ceil(0.99 * len(success)) - 1]
traffic_rps = len(records) / 10
error_ratio = len(failure) / len(records)
# These are end-of-interval gauges, not interval averages.
busy_workers, total_workers = 4, 4
queued_requests, oldest_queue_seconds = 12, 1.2

assert p99_success == 0.8 and traffic_rps == 10 and error_ratio == 0.05
assert mean(failure) < mean(success)
assert busy_workers / total_workers == 1
print(f"traffic={traffic_rps:.1f} completed requests/s; errors={error_ratio:.1%}")
print(f"success p99={p99_success:.3f}s; failed mean={mean(failure):.3f}s")
print(f"success mean={mean(success):.6f}s; all-request mean={mean(d for _, d in records):.6f}s")
print(f"worker snapshot={busy_workers}/{total_workers}; queue={queued_requests}; oldest={oldest_queue_seconds}s")

输出显示，每秒完成十次请求，错误比例为百分之五，成功请求的百分之九十九分位数为零点八秒，失败请求平均只耗时零点零零五秒。成功请求平均约零点零八九四七四秒，而加入快速失败后，全请求平均值降低到零点零八五二五秒。这个可复现的差异说明，混合平均值下降不等于业务变得更有用，必须同时查看结果是否成功。

快照中四个工作线程都处于忙碌状态，还有十二个请求排队，最老请求已经等待一点二秒。这些仪表提供资源压力背景，却没有证明整个十秒窗口的占用率始终为百分之一百。应把它们与延迟、流量定义和后续队列趋势一起阅读，再判断需要扩容、限制进入的工作量，还是调查某个变慢的依赖，避免用一个瞬时数值替代完整的故障分析。

来源

Google SRE: Monitoring Distributed Systems，四个黄金信号以及成功与失败请求的延迟，已核验 2026-09-13。
Prometheus: Instrumentation，请求服务系统与线程池埋点，已核验 2026-09-13。
Google SRE: Handling Overload，资源限制、排队与请求成本变化，已核验 2026-09-13。

指标与日志都需要明确统计总体

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

指标与日志是对已观测行为的不同表示，并不是互相竞争的真相定义。指标通常在一组维度下汇总测量结果，日志记录则描述一个事件，并能够携带更具体的上下文。只要数据覆盖与语义支持，两者都可以回答聚合问题。不能因为某张仪表盘更整齐，就认为它天然更权威；也不能因为日志字段很多，就默认其中包含完整且可直接比较的业务总体。

对于结账服务，一个已完成请求计数器可以把每个最终结果归为成功或错误。路由、结果等少量有界维度，方便持续比较流量与失败比例。诊断日志则可以利用关联编号、错误类型和依赖响应，解释某一次失败请求的具体原因。这两类信息互相帮助，但它们采用的分母仍然需要分别确定。共享服务名称或时间图形，并不足以证明两份数据统计了相同的请求集合。

先决定测量包含什么

累计计数器本身不是每秒请求数。实际速率查询需要跨时间观测，并考虑进程重启等导致的计数重置。不过，一个起点、终点和成员都明确的完整合成批次，可以直接计数。不能悄悄把生产中的时间窗口速率换成两个无关快照的比例，也不能把经过选择的事件流与覆盖全部请求的计数器混为同一个统计总体。计算形式相似，并不代表时间口径已经一致。

日志也不是只能靠人逐条阅读。只要终态事件结构稳定且记录完整，就能聚合出与请求计数器相同的总量。选择时需要考虑事件体积、索引、查询延迟、保留期限和维护复杂度。指标经常适合反复执行的汇总查询，但如果每个请求都生成一个新的标签值，指标存储也可能迅速变得昂贵。究竟哪种方式成本较低，取决于实际维度和使用方式，而不是单凭指标或日志这个名称判断。

坏掉的样子

假设一百个已完成请求里有四个失败。为了排查问题，日志系统或人工查询特意保留其中五个请求，里面包含两个失败。完整总体的失败比例是百分之四，被选日志的失败比例则是百分之四十。两次算术运算都没有错，但把后者宣称为整个服务的失败率就错了，因为这五条记录既不是全部请求，也没有证明是能够代表总体的样本。排障数据的选择目的必须与统计推断分开。

把重试过程中的失败次数当成最终失败请求数，也会造成类似误差：同一个请求的一次尝试可能失败，随后却成功完成。日志缺失、重复投递、时间窗口不同和路由归类不一致，都可能令看起来相关的图表互相矛盾。用于可靠性计算时，应明确每个请求只有一个最终结果，同时保留尝试级证据用于诊断。发现不一致后，不能只改图表标题，或者简单平均两个比例来掩盖口径差异。

快速验证

将代码保存为 metrics-logs.py，使用 Python 3，并把官方 promtool 可执行程序放入 PATH。本次完整运行采用 Python 3.12.14 与 promtool 3.14.0。真实校验器从标准输入读取生成的指标文本，不建立服务器、容器或网络连接。合成请求集合按构造保证完整，诊断日志子集则是刻意选取，并非随机抽样。程序同时输出实际工具版本，避免把历史容器版本误写成这次使用的版本。

import json
import subprocess
from collections import Counter

# A complete synthetic population, with exactly one terminal outcome per request.
requests = [{"request_id": f"r{i}", "route": "/checkout",
 "outcome": "error" if i in {7, 18, 53, 94} else "success"}
 for i in range(1, 101)]
counter = Counter(request["outcome"] for request in requests)
selected_logs = [request for i, request in enumerate(requests, 1)
 if i in {1, 7, 18, 33, 55}]
logged_errors = sum(record["outcome"] == "error" for record in selected_logs)
text = "# HELP demo_requests_total Completed synthetic requests.\n# TYPE demo_requests_total counter\n"
for outcome, count in sorted(counter.items()):
 text += f'demo_requests_total{{route="/checkout",outcome="{outcome}"}} {count}\n'
version = subprocess.run(["promtool", "--version"], capture_output=True, text=True, check=True).stdout.splitlines()[0]
result = subprocess.run(["promtool", "check", "metrics"], input=text,
 text=True, capture_output=True, timeout=30)
assert result.returncode == 0, result.stdout + result.stderr
population_rate = counter["error"] / len(requests)
selected_rate = logged_errors / len(selected_logs)
assert population_rate == 0.04 and selected_rate == 0.4
assert "request_id" not in text and len(counter) == 2
# Full event coverage would recover the same aggregate; these five logs cannot.
assert sum(r["outcome"] == "error" for r in requests) == counter["error"]
print(json.dumps({"requests": len(requests), "errors": counter["error"],
 "population_error_rate": population_rate, "exposed_metric_series": len(counter),
 "selected_logs": len(selected_logs), "selected_log_errors": logged_errors,
 "selected_log_error_rate": selected_rate,
 "exposition_validated_by": version}, indent=2))

输出应包含一百个请求、四个错误及零点零四的总体比例。筛选后的五条日志中有两个错误，得到零点四。导出文本只有两条按结果区分的计数序列，标签中不包含请求编号。Promtool 负责验证格式，Python 断言负责验证算术结果和事先定义的成员关系。这不是实际抓取流程、计数器重置处理或存储费用基准测试，因此不能把格式检查通过扩大为整套监控链路已经验证。

实际排查时，可以先用有界指标维度确定受影响的路由、结果或部署，再沿关联编号进入日志或链路，寻找单个请求的上下文。普通指标标签通常不应加入请求编号，除非已有明确的基数预算；当整套技术栈支持时，也可以通过示例数据关联追踪，而不把每个请求都变成独立序列。最后应把事件完整性、选择规则与派生比例的说明放在一起，让后来阅读图表的人能够重现它的单位、总体和时间口径。

来源

OpenTelemetry metrics，针对总体的测量与聚合，已核验 2026-09-13。
OpenTelemetry logs，事件记录及其与其他遥测信号的关系，已核验 2026-09-13。
Prometheus metric and label naming，有界标签及高基数维度的成本，已核验 2026-09-13。

告警告诉你该读什么

Tue, 22 Sep 2026 00:00:00 +0000

告警应让读者知道第一步该查什么，而不只是展示一个红色标记。它需要说明观察到的条件、受影响范围、持续时间、负责团队，以及接下来要看的证据。这些内容属于规则的可观察行为，应当和触发条件一起测试，不能等事故发生以后才把通知文案当作装饰补上。

把观察与解释分开

一次 scrape 失败，说明 Prometheus 没有成功收集目标的指标，并不能独立证明公共 API 已经不可用。服务可能仍能处理用户请求，但指标处理器失败；也可能指标采集正常，业务操作却一直报错。应该组合面向用户症状的探测与内部证据，并在告警里准确说明本次到底是哪一种观察触发，避免把采集失败直接写成业务停机。

最近发布是有价值的排查线索，却不是因果证明。证书到期、依赖故障、资源短缺或网络异常，都可能发生在没有部署的时刻。把相关变更记录和状态、日志、用户侧指标放在一起比较；在没有建立关联之前，不要把最近一次提交自动标记为根因。好的上下文帮助缩小范围，而不是提前替调查下结论。

保持身份稳定，让上下文可用

Prometheus 根据表达式返回的每组标签识别告警实例。服务、团队等稳定路由属性可以放进 labels；当前数值、解释文字和 runbook 链接放进 annotations。如果把不断变化的时间戳或测量值塞进标签，告警身份也会不断改变，pending 状态可能始终等不到持续时间结束。注解可以随情况变化提供解释，而不重新定义这是否还是同一条告警。

runbook 开头应给出可访问、只读的检查：先看目标的具体采集错误，再比较指标端点和用户请求路径，最后关联相关日志与变更记录。同时写清正常时应看到什么、看不到时进入哪个分支、什么时候升级求助。通知链接不要带凭据或敏感查询参数，还要实际确认值班读者有权访问目标页面。链接存在但读者无法打开，同样不能算有效的排查入口。

坏掉的样子

规则可能正确触发，却没有路由到任何接收人；也可能链接的文档已被删除，或者聚合时丢失了本应定位实例的标签。噪声阈值则会为不需要决策的短暂现象反复打断人。只有确实需要及时人工判断时才使用 page，其他情况应进入合适的看板、工单或自动处理。Alertmanager 的分组和抑制，与 Prometheus 判断规则是否 firing，是两段需要分别验证的流程。

可选的 for 要求表达式在连续评估中持续保持 active，达到指定时长后才进入 firing。它不是滑动平均窗口，也没有包含通知发送的等待时间。如果表达式不再产生该标签集合，本例规则就会停止活跃。尤其要注意，stale 或完全缺失的序列不是显式的零，因此告警安静不等于业务恢复；采集链路和预期目标清单需要独立监控，不能把“看不见”解释为健康。

快速验证

使用 Prometheus 发行包中的 promtool；下面实验已用 3.14.0 执行。在一个空的本地目录里，把接下来的两个代码块分别保存成 alerts.yml 和 alerts.test.yml。规则故意只描述指标采集可用性，不代表 API 可用性 SLO。severity 和 team 是测试标签，执行测试不会发送通知或改动任何现有告警配置。

groups:
 - name: api-scrape
 rules:
 - alert: APIScrapeUnavailable
 expr: up{job="api"} == 0
 for: 2m
 labels:
 severity: page
 team: platform
 annotations:
 summary: 'Cannot scrape {{ $labels.job }} on {{ $labels.instance }}'
 description: 'up == 0 for 2m. Inspect the target error and /metrics handler; scrape failure alone does not prove API downtime.'
 runbook_url: https://www.xbcatm.com/posts/a-purpose-built-health-check-is-worth-keeping/

测试使用一分钟间隔的人工样本。零分钟的失败先进入 pending，到第二分钟才 firing；第三分钟恢复后，后面再次失败仍须等待新的持续周期。预期注解不仅核对有没有告警，还核对展开后的目标名称、排查文字和 runbook URL，防止规则通过而通知内容已经失去用途。

rule_files:
 - alerts.yml
evaluation_interval: 1m
tests:
 - name: sustained failure, recovery, and recurrence
 interval: 1m
 input_series:
 - series: 'up{job="api",instance="api.example:9090"}'
 values: '0 0 0 1 0 0 0'
 alert_rule_test:
 - eval_time: 0m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - eval_time: 1m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - eval_time: 2m
 alertname: APIScrapeUnavailable
 exp_alerts: &firing
 - exp_labels:
 job: api
 instance: api.example:9090
 severity: page
 team: platform
 exp_annotations:
 summary: 'Cannot scrape api on api.example:9090'
 description: 'up == 0 for 2m. Inspect the target error and /metrics handler; scrape failure alone does not prove API downtime.'
 runbook_url: https://www.xbcatm.com/posts/a-purpose-built-health-check-is-worth-keeping/
 - eval_time: 3m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - eval_time: 5m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - eval_time: 6m
 alertname: APIScrapeUnavailable
 exp_alerts: *firing
 promql_expr_test:
 - expr: 'ALERTS{alertname="APIScrapeUnavailable",alertstate="pending"}'
 eval_time: 1m
 exp_samples:
 - labels: 'ALERTS{alertname="APIScrapeUnavailable",alertstate="pending",instance="api.example:9090",job="api",severity="page",team="platform"}'
 value: 1
 - name: transient failure does not fire
 interval: 1m
 input_series:
 - series: 'up{job="api",instance="api.example:9090"}'
 values: '1 0 1 1'
 alert_rule_test:
 - eval_time: 2m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - eval_time: 3m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 - name: stale series is not an explicit zero
 interval: 1m
 input_series:
 - series: 'up{job="api",instance="api.example:9090"}'
 values: '0 stale _ _'
 alert_rule_test:
 - eval_time: 2m
 alertname: APIScrapeUnavailable
 exp_alerts: []
 promql_expr_test:
 - expr: 'ALERTS{alertname="APIScrapeUnavailable"}'
 eval_time: 2m
 exp_samples: []

在同一目录执行：

promtool --version
promtool check rules alerts.yml
promtool test rules alerts.test.yml

规则检查和单元测试都应报告 SUCCESS。用例覆盖持续失败、pending 状态、恢复、再次触发、短暂失败，以及在触发前变为 stale 的目标。stale 用例刻意证明检测盲区，而不是把缺失样本冒充健康。全部预期标签和注解都必须相符；例如实例标签丢失或 runbook 地址变化，测试都不应默默通过。

再做一次反例检查：只修改规则里的 runbook URL，不改测试期望，测试应当失败；恢复原值后重新通过。把 for 从两分钟改为一分钟，应让第一分钟的断言失败；更小的改动可能在这个评估间隔下不可见。这样的验证能证明规则评估和说明性上下文确实受检，但不证明真实 scrape、文档访问权限、Alertmanager 分组或呼叫设备送达。生产启用前还要沿这些真实链路分别演练，不能把本地 SUCCESS 当作整条值班链路已经验收。

来源

Prometheus：告警规则，标签身份、等待时间和模板注解，已核验 2026-09-09。
Prometheus：规则单元测试，人工样本、stale 标记和预期告警输出，已核验 2026-09-09。
Google SRE：监控分布式系统，可执行的呼叫、症状和低噪声监控，已核验 2026-09-09。

直方图保留延迟分布的形状

Sun, 20 Sep 2026 00:00:00 +0000

平均值可能让一个令人不舒服的服务看起来很快。如果九十五次请求各耗时五十毫秒，另外五次耗时两秒，平均延迟也只有一百四十七点五毫秒。直方图能够在不保存每条原始请求的情况下，保留更多关于这部分慢请求的信息。但它保存的是分桶后的分布近似，不是全部原始观测，也不会天然提供精确的分位数。理解这个区别，才能避免把计算输出当成重新测得的真实延迟。

先看桶里究竟统计了什么

在 Prometheus 经典直方图中，桶的边界标签表示小于或等于该上界的全部观测。计数具有累积性：一条五十毫秒的请求，既进入一百毫秒桶，也进入所有更大的桶。正无穷桶覆盖全部观测，计数和总和组件则分别记录样本数量与累计耗时。因此，直接把所有累积桶相加会重复统计请求，不能把结果当成真实访问量。

相邻累积桶相减，可以得到互不重叠区间内的观测数量，但仍然不知道每条请求在该区间中的具体位置。边界兼容的直方图可以先把对应桶的计数相加，再估计总体分位数。直接平均多个实例已经算出的分位数，无法恢复合并后的分布，即使各实例自己的分位数都计算得很精确，也不存在这种简单的总体换算关系。

分辨率决定答案能有多精细

对于常见的正数经典桶，分位数函数先定位目标排名所在的桶，再假定该区间内的观测均匀分布，执行线性插值。真实延迟却可能集中在桶的某一侧，所以返回值是与桶宽相关的估计，并不是被重新找回的实际观测。应该围绕业务真正关心的运行区间设置边界，而不是把大部分精度浪费在与目标无关的范围内。

如果桶边界正好位于三百毫秒目标上，就可以直接统计达到该延迟要求的请求数。这通常比观察一个插值得出的高分位数是否恰好低于阈值，更贴近事件型目标的定义。不过，经典直方图每增加一条边界，都会为每组标签组合增加桶序列。现代 Prometheus 也支持原生直方图，当前文档建议在埋点及相关系统支持时优先考虑；标准指数型原生桶采用不同的插值方式，下面的实验特意只讨论经典桶。

坏掉的样子

上层桶过宽时，少量观测移动就可能让尾部估计出现看起来很大的跳跃。经典分位数计算还要求存在正无穷桶，遗漏它可能使结果无效。如果目标排名落在最后的无限桶中，Prometheus 会返回前一个有限桶的上界，而不是编造一个无限延迟。上述输出都不能告诉你最慢那条请求的准确耗时，追查单次异常仍需要更细的观测材料。

空样本总体没有可解释的观测分位数。跨实例桶边界不匹配、同一指标混入不同单位，或者累积计数出现不合法的下降，也会破坏结果含义。按时间查询累计计数器时，应先计算合适的增量或速率，再聚合实例，使重置得到正确处理。另外，全请求分布也要说明结果范围：快速失败可能降低表面延迟，却同时让服务变得更不可用，不能仅凭曲线变快就宣布改善。

快速验证

保存为 histogram-shape.py，使用 Python 3 执行。程序先从人工构造的原始样本计算精确的最近秩高分位数，再分别根据两套经典桶估计相同分位点。精简插值函数只适用于这里的正数、非空样本，并断言选中的桶有有限边界；它用于展示桶内假设，不替代 Prometheus 对所有特殊输入和边界情况的完整实现。

from math import ceil, inf
from statistics import mean

values = [0.05] * 95 + [2.0] * 5
coarse = [0.1, 0.3, 1.0, 5.0, inf]
fine = [0.1, 0.3, 1.0, 2.0, 5.0, inf]

def cumulative(bounds):
 return [sum(value <= bound for value in values) for bound in bounds]

def estimate_p99(bounds):
 counts = cumulative(bounds)
 rank = 0.99 * counts[-1]
 lower, previous = 0.0, 0
 for upper, count in zip(bounds, counts):
 if count >= rank:
 assert upper != inf and count > previous
 return lower + (upper - lower) * (rank - previous) / (count - previous)
 lower, previous = upper, count
 raise AssertionError('rank not covered')

exact = sorted(values)[ceil(0.99 * len(values)) - 1]
counts = cumulative(coarse)
increments = [counts[0]] + [right - left for left, right in zip(counts, counts[1:])]
assert counts == [95, 95, 95, 100, 100]
assert increments == [95, 0, 0, 5, 0] and sum(increments) == 100
assert exact == 2.0 and abs(estimate_p99(coarse) - 4.2) < 1e-12
assert abs(estimate_p99(fine) - 1.8) < 1e-12
print(f"mean={mean(values):.4f}s; raw nearest-rank p99={exact:.1f}s")
print(f"coarse cumulative counts={counts}; sum_of_buckets={sum(counts)}")
print(f"classic linear p99: coarse={estimate_p99(coarse):.1f}s; fine={estimate_p99(fine):.1f}s")
print(f"at or below 0.3s={counts[1]}/{counts[-1]}")

原始样本的百分之九十九分位数为两秒，粗桶却给出四点二秒，因为有关观测只被定位在一秒到五秒之间。增加两秒边界后，估计变成一点八秒。在这组数据中，较窄的桶确实减少了误差，但仍然没有等于真实样本分位数，说明提高分辨率不会凭空恢复原始数值。原记录还将两项估计与 Prometheus 3.5.1 的实际分位数函数做了核对，在万亿分之一的数值容差内一致。排障时应先查看所在区间和边界，再解释分位数的小幅变化。

累积桶计数相加得到四百八十五，而实际只有一百条请求；换成互斥区间增量后，总和才是一百。零点三秒边界对应的桶还直接给出九十五条达标、总计一百条的精确阈值结果。把这些输出一起看，才能区分两种能力：与边界对齐的阈值计数可以准确，桶内插值得到的分位数仍然只是近似。

来源

Prometheus: Histograms and Summaries，分布表达、聚合与原生直方图，已核验 2026-09-13。
Prometheus: histogram_quantile，经典桶插值与边界情况，已核验 2026-09-13。
Google SRE: Monitoring Distributed Systems，延迟长尾与有意义的监控，已核验 2026-09-13。

监控 · XB 现场笔记

iotop 能看出是哪个进程在烧磁盘

逐个进程的计数器

看到谁在扫盘

先看再动

坏掉的样子

快速验证

延伸阅读

来源

Grafana 变量必须与查询语言的语义一致

检查最终送出的表达式

坏掉的样子

快速验证

延伸阅读

来源

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

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

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

坏掉的样子

快速验证

来源

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

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

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

坏掉的样子

快速验证

延伸阅读

来源

基数是指标的预算

统计真正出现的组合

把指标表示方式一起算进去

坏掉的样子

快速验证

延伸阅读

来源

看板是总结，不是放大镜

给页面安排清楚的阅读顺序

保留请求权重和观测覆盖

坏掉的样子

快速验证

延伸阅读

来源

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

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

序列已有的标签优先

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

坏掉的样子

快速验证

来源

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

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

先确定要询问哪一种缺失

坏掉的样子

快速验证

来源

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

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

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

坏掉的样子

快速验证

来源

健康的黄金信号

区分用户体验与工作需求

说明失败条件与资源压力

坏掉的样子

快速验证

延伸阅读

来源

指标与日志都需要明确统计总体

先决定测量包含什么

坏掉的样子

快速验证

延伸阅读

来源

告警告诉你该读什么

把观察与解释分开

保持身份稳定，让上下文可用

坏掉的样子

快速验证

延伸阅读