sitespeed.io 性能回归告警实战:基于 Grafana 与 Graphite 的告警规则配置指南
sitespeed.io 性能回归告警实战:基于 Grafana 与 Graphite 的告警规则配置指南
本篇技术指南围绕 sitespeed.io 官方告警文档展开,讲解如何把 Browsertime、Coach、PageXray 等插件产出的性能指标存入 Graphite,再借助 Grafana 建立"性能回归告警"——当 Speed Index、First Visual Change 等指标劣化到指定阈值时,自动通过 Slack、PagerDuty 或邮件通知团队。读完本文,你将掌握两种告警建模方式(百分比变化告警与指标差值告警)、历史趋势图配置,以及针对资源体积、404/50x、console.error、Coach 隐私分等场景的实战告警模板。
告警的前提:指标先进入 Graphite/Grafana
性能告警的一切都建立在"指标持续、稳定地写入时序存储"之上。sitespeed.io 通过 Graphite 插件 把每个 URL 的聚合指标发送到 Graphite(也支持 InfluxDB 与 StatsD 接口),再由 Grafana 以 Graphite 为数据源完成查询与告警。
关键 CLI 参数与默认值
发送指标至少需要指定 Graphite 主机,其余参数在 lib/cli/options/graphite.js 中定义,常用项如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--graphite.host |
无 | Graphite 主机地址(必填),用于存储采集到的指标 |
--graphite.port |
2003 |
Graphite 数据写入端口(carbon) |
--graphite.httpPort |
8080 |
Graphite 用户界面端口,也用于发送注解(annotation) |
--graphite.auth |
无 | 认证信息,格式 user:password |
--graphite.webHost |
无 | graphite-web 主机,未设置时使用 graphite.host |
--graphite.namespace |
sitespeed_io.default |
所有指标键的前缀命名空间 |
--graphite.addSlugToKey |
true |
把测试 slug(--slug)作为命名空间下一级键写入,默认开启 |
--graphite.messages |
pageSummary,summary |
发送哪些消息;要拿单次运行的原始指标可加 run |
--graphite.includeQueryParams |
false |
是否把 URL 查询参数计入 Graphite 键 |
--graphite.sendAnnotation |
true |
每次运行结束后是否发送注解(需配置 --resultBaseURL) |
--graphite.annotationRetentionMinutes |
无 | 注解与 Graphite 保留精度对齐的分钟数 |
一个最小可用的运行示例(来自性能面板文档):
sitespeed.io https://www.sitespeed.io -n 1 --slug myTest --graphite.host 127.0.0.1
指标键是怎么生成的
Grafana 查询面板里的每一个指标路径,都由 data-generator.js 的 keyPathFromMessage 拼接而成:namespace + 消息类型 + 浏览器 + 网络连接类型 + URL 分组 + 具体指标路径。若开启了 --graphite.addSlugToKey 且设置了 --slug,slug 还会插入到命名空间之后,最终形态类似:
sitespeed_io.default.firstView.pageSummary.www_sitespeed_io._.chrome.native.browsertime.statistics.timings.pageTimings.backEndTime.median 231 1532591185
例如用 --slug firstView --graphite.namespace sitespeed_io.desktop,键会以 sitespeed_io.desktop.firstView. 开头,这也正是 Grafana 默认面板可以正确显示截图与视频的原因。
可以针对哪些指标告警
所有写入存储的指标都可以告警。核心的可视化指标(Visual Metrics)路径在 lib/support/friendlynames.js 中登记,例如:
FirstVisualChange→statistics.visualMetrics.FirstVisualChange.median(视口内第一次有内容绘制的时刻)LastVisualChange→statistics.visualMetrics.LastVisualChange.medianSpeedIndex→statistics.visualMetrics.SpeedIndex.median(视口可见部分显示完成的平均时间)
这些指标的定义可查阅指标文档。需要留意的是,面板与告警中默认使用多次运行的中位数(median),因此想让指标更稳定,就应增大每个 URL 的测试次数(-n)。
两种告警建模思路
告警文档给出了两种可独立使用的建模方式,选择哪一种取决于你的监控目标:
- 百分比变化告警(Percentage queries):计算指标在时间轴上的变化百分比,当"所有被测 URL"的变化都超过某个百分比时才触发。适合捕捉"整体性能趋势性劣化"。
- 指标差值告警(Metrics queries):对指标与 X 时间之前的值做差,当差值超过某个绝对值并持续一段时间时触发。适合对具体指标(如 First Visual Change 增加 20ms)设定硬性阈值。
下文分别展开。
方案一:创建百分比变化告警
百分比告警的核心理念是多 URL 确认:同时测试三个 URL,只有当三个 URL 的变化都大于 3% 时才触发告警,从而排除"某个 URL 单独波动"造成的误报。
图中左侧是变化百分比序列,这是真正挂告警的数值;右侧是对应数值的变化曲线。红色水平线表示告警触发(发送邮件、发布到 Slack/PagerDuty 等),绿色水平线表示指标恢复正常。触发阈值的选取取决于指标本身的稳定度——你的网站是否稳定、是否走代理测试、运行浏览器的服务器实例大小等都会影响。
构建百分比查询
在 Grafana 面板中构建查询时,需要一个"对比基线"和一个"当前窗口":
- 基线:取一天前的移动中位数(moving median),作为对比基准;
- 当前窗口:取最近 5 小时的移动中位数。
如果你的运行环境非常稳定(例如有代理、实例规格固定),可以不做多小时的移动中位数,直接取最近一次运行值即可;反之,如果环境很不稳定,则应把时间窗口拉得更长,用更平滑的曲线过滤抖动。
三个 URL 的查询分别类似:
随后把坐标轴(Axes)单位改为百分比显示,范围设为 0.0–1.0:
配置百分比告警规则
查询就绪后创建告警规则:选择告警所依据的聚合方式(取中位数)、时间跨度,以及触发百分比阈值。文档示例使用 AND 组合——所有 URL 都必须变化才告警;如果你关心的是"任意一个 URL 发生变化",也可以改用 OR 逻辑。
示例中告警评估频率为每小时一次。评估频率应与你的发布/内容更新节奏匹配,目标是至少在数小时内捕获到一次回归——评估间隔过长,回归会长时间处于"未被发现"状态。
方案二:创建指标差值告警
如果你不想用百分比,也可以直接对"指标差值的绝对值"设置阈值。示例场景:三个 URL 的 First Visual Change 若比基准增加 20ms 就告警。
这类查询比百分比更直白:取出你关心的指标,用该指标与 X 时间之前的值做差(diff),把差值画出来。查询配置参考下图:
配置差值告警
差值告警的关键在于"持续确认":示例中告警查询每小时运行一次,并且需要在 2 小时内连续触发 2 次才真正发送告警。也就是说,只要你的测试至少每小时跑一次,两次连续运行的值都超过阈值,才会最终触发——这样可以有效过滤偶发的单次尖刺。
历史趋势图(History graph)
告警不是终点,还需要一张历史趋势图来观察回归的时间跨度。配置要点有二:
- 查询:列出你想看的指标,并选择回溯的时间范围。文档建议从 30 天改为 7 天——30 天适合看长期趋势,但真正发生回归时,7 天窗口更能让人迅速定位劣化起点;
- 聚合:默认取移动中位数(moving median),你可以根据指标稳定度自行尝试其他聚合方式。
最终把面板时间范围固定为最近 7 天:
更多实战告警场景
除核心性能指标外,文档还提供了四类高频实用告警模板。
1. 资源体积增长告警
如果团队并不能完全掌控所有被推送的代码(例如引用了第三方 JS),可以对响应体大小建告警。下图演示对 JavaScript 与 CSS 体积的监控:
对应查询从 PageXray 的响应类型数据中取大小指标:
2. 404 / 50x 错误响应告警
页面偶尔会引用到不存在的资源(404)或返回服务器错误(50x),这类错误同样可以告警:
查询时按响应码做过滤与排除,excludes 部分需要按你的实际情况修改,只保留关心的错误码:
3. console.error 告警(Chrome)
如果你使用 Chrome 测试,sitespeed.io 会收集控制台日志数据。页面出现 JavaScript 错误时,即可触发告警。查询写法参考:
配置告警时有个关键细节:把 If no data or all values are null(无数据或所有值为 null)设置为 No data 或 Ok,这样当页面没有产生任何错误、查询无数据时不会误发告警。
4. Coach 隐私分过低告警
Coach 输出的 privacy 指标是最值得关注的指标之一——它反映你是否妥善保护用户、有没有把用户隐私数据分享给第三方公司/网站。隐私分从 Coach 查询得到:
配置告警时务必对低于当前值的下降方向告警(告警方向与性能指标相反——性能指标是超阈值告警,评分指标是低于阈值告警):
告警质量的关键:存储保留策略与数据对齐
告警建立在历史数据之上,因此 Graphite 的存储配置直接影响可回溯范围与查询粒度。仓库自带的示例配置在 docker/graphite/conf/storage-schemas.conf,三类数据的保留策略如下:
| 数据类别 | pattern | retentions |
|---|---|---|
| 汇总数据(summary/pageSummary) | ^sitespeed_io\. |
1h:65d(每小时一点,保留 65 天) |
单次运行数据(run 消息) |
^sitespeed_io\.(.*)\.(.*)\.run\. |
10s:8d(每 10 秒一点,保留 8 天) |
| CrUX 数据 | ^sitespeed_io\.crux\. |
1d:2y(每天一点,保留 2 年) |
配置要点(详见 Graphite 文档):
- 聚合粒度决定告警灵敏度:如果只按小时聚合(
1h:65d),那么同一小时内多次运行的数据会被合并,适合每小时跑一次的常规监控;若要在告警中看到更细的波动,可参考文档中10s:6h,10m:60d,30m:90d的多级保留示例。 - 注解与存储对齐:发送到 Graphite 的注解默认标记运行时刻。若存储粒度为 10 分钟,请配置
--graphite.annotationRetentionMinutes 10,让注解与指标点在 Grafana 上对齐,否则可能出现"注解时刻与数据点时刻不一致"的视觉偏差。 - 运行数据开启:需要按单次运行原始值告警(不做中位数聚合)时,把
run加入--graphite.messages,例如--graphite.messages pageSummary summary run。
在 Grafana 侧,数据源由 datasources/graphite.yaml 通过 provisioning 自动注入(默认 URL http://graphite:80、Basic Auth guest/guest),仪表盘则由 dashboards/default.yaml 提供。若想用 Docker Compose 一键拉起整套环境,仓库根目录的 docker-compose.yml 已包含 Grafana 12.2.0 与 Graphite(Grafana 面板端口 3000、Graphite 写入端口 2003、Web 端口 8080),并预置了 PageMetrics.json 等示例面板。
运行频率与告警评估的配合建议
告警文档反复强调两点配合原则:
- 测试频率 ≥ 告警评估频率:告警"2 小时内触发 2 次"的前提是测试本身至少每小时跑一次。通常用 cron 或 CI 定时任务驱动
sitespeed.io ... --graphite.host ...,再在 Grafana 中设置对应的评估间隔。 - 评估窗口不宜过长:无论百分比告警还是差值告警,目标都是"发布或内容变更后的数小时内感知回归"。窗口过长,告警会失去时效性。
小结:同一套方法论可以复用到所有指标
百分比、差值、历史趋势这套组合并不局限于文中的示例——它适用于你发送到 Graphite 的一切指标:Browsertime 的视觉指标、PageXray 的资源与响应码、Coach 的各类评分、WebPageTest 数据,乃至你自己在存储中的自定义指标。例如在移动端场景中,Wikipedia 这类内容稳定的站点,First Visual Change 的曲线会相当平稳(见下图),阈值可以设得更紧:
实践建议总结如下:
- 先用 7 天历史趋势图观察指标的"自然抖动幅度",再据此设定告警阈值;
- 优先采用多 URL AND 组合,过滤单点波动造成的误报;
- 评分类指标(如 Coach 隐私分)记得把告警方向设为"低于阈值";
- 无数据类错误(如 console.error)把空数据状态配置为不触发;
- 保证测试频率与 Grafana 评估频率匹配,并留出至少数小时内的告警响应余量。

















