sitespeed.io Matrix 消息推送实战:配置、预算结果与错误告警的完整指南

原创2026-10-13 13:40:411,648 阅读
文章标签:测试性能剖析指标监控

sitespeed.io Matrix 消息推送实战:配置、预算结果与错误告警的完整指南

导读:本文围绕 sitespeed.io 内置的 Matrix 插件,讲解如何把性能测试的预算结果(通过/失败/错误)与测试运行错误实时推送到 Matrix(Element)客户端。读完本文,你将掌握 --matrix.host、--matrix.accessToken、--matrix.room 等全部配置参数、按消息类型分房间路由的用法,并结合仓库源码理解消息的构造、发送与重试机制,从而把性能预算监控接入自己的聊天与告警工作流。

Matrix 插件能做什么

Matrix 是一个开源、去中心化的安全通信网络,Element 是其中最常用的客户端之一。sitespeed.io 的 Matrix 插件(源码位于 lib/plugins/matrix/index.js)让你把两类消息直接发到 Matrix 房间:

  1. 预算消息(budget):页面通过性能预算、页面未通过预算(列出具体超标的指标与数值)、以及预算执行出错(如某 URL 无法测试)时的消息;
  2. 错误消息(error):测试运行过程中产生的错误(例如浏览器/设备启动失败、脚本执行异常),方便你及时掌握测试本身是否正常工作。

插件的 messageTypes() 方法明确了当前支持的两种消息类型,它同时被 CLI 选项解析所引用:

// lib/plugins/matrix/index.js
export function messageTypes() {
  return ['error', 'budget'];
}

配置 Matrix 通知

必需参数

要让 sitespeed.io 把消息发送到 Matrix,至少需要配置以下三个参数:

参数 说明
--matrix.host 你的 Matrix 服务器主机地址,例如 matrix.example.com
--matrix.accessToken 你的用户访问令牌(Access Token),可通过 Matrix 客户端 API 获取
--matrix.room 默认房间 ID,sitespeed.io 会把消息发送到这个房间

在插件初始化阶段,源码会用 throwIfMissing 校验这三个参数,缺失任何一个都会直接报错,确保配置在运行时是完整的:

// lib/plugins/matrix/index.js(open 方法)
throwIfMissing(options.matrix, ['accessToken', 'host', 'room'], 'matrix');

这些 CLI 选项定义在 lib/cli/options/matrix.js,运行 sitespeed.io --help 时也会在 Matrix 分组下看到它们。

可选参数

参数 说明
--matrix.messages 选择要发送的消息类型,可选值为 error、budget;默认两者都发送,即 ["error","budget"]
--matrix.rooms 按消息类型把消息路由到不同房间,例如 --matrix.rooms.error 房间A --matrix.rooms.budget 房间B

推荐使用配置文件

官方文档建议通过配置文件来管理 Matrix 配置。下面是一个完整的示例(matrix-config.json):

{
  "matrix": {
    "host": "myhost.com",
    "room": "THE_DEFAULT_ROOM",
    "accessToken": "THEVERYLONGTOKEN",
    "rooms": {
      "budget": "THE_ROOM_FOR_BUDGET_MESSAGES",
      "error": "THE_ROOM_FOR_ERROR_MESSAGES"
    }
  }
}
  • 没有配置 matrix.rooms 时,所有消息都发往默认的 room;
  • 配置了 matrix.rooms 后,budget 消息发往 rooms.budget,error 消息发往 rooms.error,实现"告警分流"。

命令行直接运行

不借助配置文件时,也可以把所有参数放到命令行(以 Docker 运行方式为例,参数说明以当前仓库 lib/cli/options/matrix.js 为准):

docker run --rm -v "$(pwd):/sitespeed.io" sitespeedio/sitespeed.io \
  https://www.sitespeed.io/ -b chrome -n 3 \
  --matrix.host matrix.example.com \
  --matrix.accessToken YOUR_TOKEN \
  --matrix.room YOUR_DEFAULT_ROOM

如需只发送预算消息、并将错误消息发到单独房间:

--matrix.messages budget \
--matrix.rooms.budget YOUR_BUDGET_ROOM \
--matrix.rooms.error YOUR_ERROR_ROOM

消息如何按类型路由到房间

在插件处理消息时,房间的选择遵循"优先使用类型专属房间,回退到默认房间"的规则。源码中多次出现这一模式:

// lib/plugins/matrix/index.js
// 错误消息在渲染阶段发送
const room = get(options, 'rooms.error', options.room);
// 预算消息在预算结果产生时发送
const room = get(options, 'rooms.budget', options.room);

其中 get 是项目自带的 objectPath 工具(lib/support/objectPath.js#L17),作用是从配置对象中按路径取值并支持默认值。这意味着 rooms.error 和 rooms.budget 是可选的覆盖项,未配置时自动落到 room。

错误消息:掌握测试是否正常工作

Matrix 插件处理 error 类型消息的逻辑位于 lib/plugins/matrix/index.js 的 case 'error' 分支。它有两个值得注意的设计:

1. 批量聚合发送,避免触发限流。 源码注释明确说明:如果逐条发送错误消息,可能瞬间发出太多请求导致 Matrix 返回 429(Too Many Requests)。因此插件先把所有错误文本拼接进 this.errorTexts,等到渲染阶段(sitespeedio.render 消息)才一次性发出:

case 'error': {
  // We can send too many messages to Matrix and get 429 so instead
  // we bulk send them all one time
  if (options.messages.includes('error')) {
    this.errorTexts += `&#9888;&#65039; Error from <b>${
      message.source
    }</b> testing ${message.url || ''} <pre>${message.data}</pre>`;
  }
  break;
}

case 'sitespeedio.render': {
  if (this.errorTexts !== '') {
    const room = get(options, 'rooms.error', options.room);
    try {
      const answer = await send(options.host, room, options.accessToken, this.errorTexts);
    } catch { /* TODO */ }
  }
  break;
}

错误消息内容包含消息来源(message.source,例如 browsertime)、被测 URL 以及错误详情 message.data。这些 error 消息由测试过程中各插件发出,例如 Browsertime 插件在浏览器/脚本运行失败时通过 super.sendMessage('error', ...) 上报(见 lib/plugins/browsertime/index.js),并会在队列层被统一登记(见 lib/core/queueHandler.js)。

2. 错误示例。 下图是一条典型的错误通知:显示测试文件 tests/ZY2242HJDX-Moto-G4/random.js 运行失败,错误为 FailError: Failure: 'device 'ZY2242HJDX' not found'(未找到测试设备)。

Matrix 收到的错误消息示例

预算消息:通过、失败与错误

预算消息是 Matrix 插件最主要的应用场景。它消费的是 Budget 插件发出的 budget.result 消息(见 lib/plugins/budget/index.js),该消息在 sitespeedio.prepareToRender 阶段由 lib/plugins/budget/verify.js 的验证结果汇总而来,结构上包含三个按 URL 分组的对象:

  • failing:未通过预算的 URL 及其超标指标;
  • working:通过预算的 URL;
  • error:测试出现错误的 URL。

全部通过

当 failing 与 error 均为空时,Matrix 会收到一条祝贺消息,文案形如:

🎉 All (50) URLs passed the budget.

消息中还会带上测试名称(如果配置了 --name)以及浏览器/设备信息。浏览器信息来自 browsertime.browser 消息,插件通过 getBrowserData() 组装,包含浏览器名称、版本,以及 Android 设备时的型号(model)、系统版本(androidVersion)与设备 ID(id):

// lib/plugins/matrix/index.js
function getBrowserData(data) {
  return data && data.browser
    ? `${data.browser.name} ${data.browser.version} ...android.model... android.androidVersion... android.id...`
    : '';
}

预算全部通过的 Matrix 消息示例

上图中可以看到:All (50) URLs passed the budget.,测试对象为随机页面,浏览器为 Chrome 86.0.4240.110。

存在失败

当存在未通过预算的 URL 时,消息会以 <h1> 标题列出失败数量,随后逐条列出失败 URL 及每个超标指标的实际值 vs 限制值,例如:

  • Total Blocking Time : 2.055s (2.000s)——总阻塞时间超过阈值;
  • Long Task : 16 (15)——长任务数量超过阈值。

预算失败的 Matrix 消息示例

上图为真实示例:Budget failing (24 URLs),测试对象为英文维基百科页面,设备为 Moto G Play 7.1.1(设备 ID ZY2242HJDX),并逐条列出了总阻塞时间、长任务数量等超标项。

从源码看,失败消息的构造逻辑会为每个 URL 生成"结果页链接"和"截图链接"(当配置了结果存储基础 URL 时),方便直接跳转到 HTML 报告核查:

text += this.resultUrls.hasBaseUrl()
  ? ` (<a href="${...}index.html">result</a> - <a href="${...}data/screenshots/1/afterPageCompleteCheck.${this.screenshotType}">screenshot</a>)`
  : '</h5>';

预算测试出错

当某些 URL 测试本身出错(如页面无法加载)时,消息会以 Budget errors testing N URLs 标题列出出错的 URL 与错误详情(<pre> 代码块)。

与上传存储联动:等待上传完成再发送

插件还支持与 GCS、S3、FTP、SCP 等存储插件联动:当收到 gcs.setup、ftp.setup、s3.setup 消息时,会设置 this.waitForUpload = true,此时预算消息不会立即发送,而是暂存在 this.budgetText 中,直到收到对应的 *.finished 消息后再发送——这样预算通知里能带上完整的结果链接/截图(截图已上传):

case 'gcs.finished':
case 'scp.finished':
case 'ftp.finished':
case 's3.finished': {
  if (this.waitForUpload && options.messages.includes('budget')) {
    const room = get(options, 'rooms.budget', options.room);
    await send(options.host, room, options.accessToken, this.budgetText);
  }
  break;
}

预算本身如何判定(背景原理)

budget.result 中的 failing/working 由 lib/plugins/budget/verify.js 逐 URL 校验产生。其判定规则是:对 timings、requests、transferSize、thirdParty、score 等配置项,Coach / Lighthouse / GPSI 的评分类指标采用 min 语义(得分低于预算即失败),其余计时、请求数、体积类指标采用 max 语义(数值高于预算即失败)。这与 Matrix 消息中"指标 : 实际值 (限制值)"的展示一一对应。完整的预算文件写法可参考仓库文档 性能预算配置。

底层发送实现:向 Matrix 客户端 API 发消息

消息的实际投递由 lib/plugins/matrix/send.js 完成,它直接调用 Matrix 客户端-服务器 API,没有依赖额外的 SDK:

  • HTTP 端点:POST https://{host}/_matrix/client/r0/rooms/{room}/send/m.room.message?access_token={accessToken},固定使用 443 端口;
  • 消息格式:msgtype: 'm.notice',并声明 format: 'org.matrix.custom.html',把插件构造的 HTML 内容放入 formatted_body 字段,从而在 Element 等客户端中渲染出标题、列表、链接等富文本效果;
  • 重试与退避:当服务端返回 408、429、500、503 时,最多重试 3 次,每次等待时间从 5 秒起、逐次翻倍(5s → 10s → 20s),其他错误码则直接记录日志并拒绝:
// lib/plugins/matrix/send.js
const retryCodes = new Set([408, 429, 500, 503]);
// 失败后 setTimeout 递归调用 send,retries - 1, backoff * 2

这个设计保证了在 Matrix 服务暂时不可用或限流时,消息仍有较高概率送达。

常见问题与排查建议

  1. 提示缺少配置:启动时若出现 matrix 相关配置校验错误,请检查 matrix.host、matrix.accessToken、matrix.room 三者是否齐全(源码在插件 open 阶段强制校验)。
  2. 收不到错误消息:确认没有用 --matrix.messages 把 error 排除掉;错误消息是聚合后在一次渲染结束时发送的,所以是批量到达而非逐条实时到达。
  3. 收不到预算消息但配置了 S3/GCS:注意 *.finished 依赖上传完成事件,请检查上传插件是否正常工作,否则预算消息会被暂存而不发送。
  4. 消息显示为纯文本而非富文本:消息以 m.notice + org.matrix.custom.html 发送,请在支持 HTML 渲染的 Matrix 客户端(如 Element)中查看。
  5. 发送被限流:send.js 对 429 等状态码内置了指数退避重试,若仍频繁失败,可以检查 Matrix 服务端限流策略或拆分监控频率。

总结

Matrix 插件为 sitespeed.io 的"性能预算 + 持续监控"工作流提供了轻量的消息出口:三类必需参数即可连通 Matrix 房间,matrix.rooms 实现预算/错误消息分流,批量聚合发送避免限流,HTML 富文本让通过/失败/错误三类结果一目了然。结合性能预算与上传存储,你可以把预算告警、错误通知无缝接入团队日常使用的 Matrix 聊天频道,实现性能监控的闭环反馈。

登录后查看全文
sitespeed.io