状态页与 SLA:对外承诺是怎么算出来的
Alioth 技术笔记 · 第 19 篇 · 状态页 / SLA 仓库:github.com/aide-family... | 在线演示:web.alioth.asia/
导语
状态页是最容易"美化"的东西:手写一个绿板子,故障时忘了改,对外就是永远 99.99%。要让承诺可信,只有一条路------每一个数字都能从原始数据重算出来。Alioth 的状态页由三部分组成:目标组的当前状态、24h/7d/30d 的可用率、以及最近的事件列表。这篇讲它们各自的数据来源,以及为什么可用率不能拿告警事件来算。
一、公开页面用 token,不用登录
go
page, err := r.client.StatusPage.Query().Where(
statuspage.TokenEQ(token),
statuspage.StatusEQ(statuspage.StatusACTIVE),
statuspage.DeletedAtIsNil(),
).Only(ctx)
token 是 16 字节随机数的十六进制串,创建状态页时生成,可以随时轮换(旧的立刻失效)。公开访问只校验 token + 页面状态,然后还要校验租户本身是 ACTIVE 且未删除:
go
active := tx.Namespace.Query().Where(
namespace.UIDEQ(page.NamespaceUID),
namespace.StatusEQ(namespace.StatusACTIVE),
namespace.DeletedAtIsNil(),
).Exist(ctx)
if !active { return nil, merr.NotFound("status page not found") }
租户被停用或归档后,它对外发布的页面必须一起下线------否则会出现"内部已经停服,外面还挂着绿色状态页"的情况。
NotFound 的用法也值得说:不存在、已停用、租户不活跃,三种情况返回同一个 404。如果分别返回不同错误,等于提供了一个"这个 token 是否存在"的探测器。
二、组件的状态:以最新一次探测为准
状态页的一个组件就是一个探测目标组。判定逻辑很短,但每个分支都有理由:
go
if hasResult {
component.LastCheckedAt = &lastChecked
switch {
case fault: // 任一目标最近一次失败
component.Status = "FAULT"
case now.Sub(lastChecked) > 10*time.Minute: // 太久没有新结果
component.Status = "UNKNOWN"
default:
component.Status = "OK"
}
}
三个细节:
- 没有任何探测结果时保持
UNKNOWN,不是OK。新加的目标组还没有数据,显示绿色是在撒谎。 - 超过 10 分钟没有新结果就降级为
UNKNOWN,而不是沿用上一个状态。探测停了(Agent 挂了、调度停了)时页面必须暴露"我不知道",而不是停留在最后一次的好状态。 - 任一目标失败即
FAULT。组件级状态取最差值------对外的承诺是"这个服务可用",一个入口挂了就是挂了。
三、可用率来自日聚合,不来自告警事件
这是状态页里最重要的一个决定。可用率的公式很朴素:ok_checks / checks,数据来自 probe_sla_dailies:
sql
INSERT INTO probe_sla_dailies (uid, namespace_uid, group_uid, target_uid, day, checks, ok_checks, ...)
SELECT gen_random_uuid()::text, namespace_uid, group_uid, target_uid, date_trunc('day', probed_at), count(*),
count(*) FILTER (WHERE ok), count(*) FILTER (WHERE NOT ok), ...
FROM probe_results
WHERE probed_at >= $1
GROUP BY namespace_uid, group_uid, target_uid, date_trunc('day', probed_at)
ON CONFLICT (target_uid, day) DO UPDATE SET ...
为什么不用告警事件算?因为两者衡量的不是同一件事:
- 告警事件依赖"规则配置"------阈值改一次,历史统计跟着变,SLA 就失去了可追溯性;
- 告警事件依赖"有人配了规则"------某个目标没配规则,它的故障不会产生事件,但探测结果是失败的;
- 探测结果是客观观测,与告警规则无关,重跑聚合就能得到同一个数字。
ON CONFLICT ... DO UPDATE 让聚合可以重复执行:从某一天起重算,结果幂等。这比"增量累加"安全得多------增量一旦算错,只能靠人肉对账。
四、滚动窗口:按 UTC 自然日过滤再累加
go
rows := Query().Where(
probesladaily.GroupUIDEQ(groupUID),
probesladaily.DayGTE(utcDay(from)),
probesladaily.DayLTE(utcDay(to)),
).All(ctx)
checks, okChecks := 0, 0
for _, row := range rows { checks += row.Checks; okChecks += row.OkChecks }
return formatAvailability(okChecks, checks), nil
三个窗口(24h / 7d / 30d)共用这一个函数,只是 from 不同。没有任何缓存,每次访问都重新累加------数据量是"天数 × 目标数",几十万行以内都是毫秒级,不值得为它引入缓存和失效逻辑。
没有数据时返回空字符串 ,而不是 100%:
go
// groupAvailability 从日聚合里汇总窗口内的可用率;没有数据时返回空字符串。
前端显示"---",而不是"100.00%"。这是状态页的底线:没有观测到的东西,不能显示成好。
五、P95 的诚实标注
go
// rawRetention 约为原始探测结果的保留窗口(7 天)。超过这个窗口的 P95
// 无法从原始结果精确计算,报表用日聚合的最大延迟近似并标注。
const rawRetention = 7 * 24 * time.Hour
P95 需要原始样本,而原始结果只保留约 7 天。所以 SLA 报表里有一个 P95Approximate 标记:窗口内超过 7 天时,用日聚合的最大延迟近似,并在界面上标出来。
很多系统在这里直接算个数字就完事,用户以为那是精确值。"近似并标注"比"精确但撒谎"更专业------尤其对外的 SLA 文档,一个数字被质疑时,你得能说清它怎么来的。
六、事件列表:只认探测事件
go
rows := Query().Where(
alertevent.NamespaceUIDEQ(namespaceUID),
alertevent.LabelsContains("probe_kind"),
).Order(Desc(FieldStartsAt)).Limit(200).All(ctx)
// 再按标签里的目标组名过滤:labels["datasource"] == 组名
两个约束:只取带 probe_kind 标签的事件(探测事件),且组名必须属于这个状态页配置的目标组。所以同一个租户的指标告警不会漏到公开页面上------公开页面只应该暴露"对外服务是否可用",而不是内部的 CPU 告警。
活跃事件全部列出,已恢复的最多展示 10 条:
go
if row.Status == "FIRING" { page.ActiveEvents = append(...) ; continue }
if recent < 10 { page.RecentEvents = append(...); recent++ }
限 10 条是产品决定:状态页的读者关心"现在有没有事、最近出过什么事",不需要一份完整历史。完整历史在管理台。
七、几个真实的坑
- 状态页的权限是两套。 管理端走
status_page:read/write/delete(租户权限),公开端只认 token。公开端不能复用管理端接口,否则每次访问都要伪造一个租户上下文。 - token 泄露要能止血。
RegenerateStatusPageToken换新 token,旧链接立刻 404------这就是"轮换"而不是"另建一个"。 - 组件按
created_at排序。 用户看到的顺序应该稳定,不能随数据库返回顺序变化。 - 跨天边界用 UTC。 聚合按
date_trunc('day', probed_at)(UTC)切,查询窗口也用utcDay对齐。混用本地时区会让某个窗口多算或少算一天,而错误只在月初/月末显现。
八、怎么验证
可以先读 app/alioth/internal/data/status_page_repo.go 与 probe_sla_repo.go 的 Rollup 实现;权限点定义在 perm 的 status_page:*,业务侧入口在 app/alioth/internal/biz/statuspage/statuspage.go。手工验证:
bash
git clone https://github.com/aide-family/moon.git && cd moon
make dev-up
open http://127.0.0.1:8080
建一个目标组、一条 HTTP 探测规则,等几分钟让探测结果进来;创建状态页并勾选该目标组,打开公开链接,应该看到组件为"正常"、24h 可用率有数字。把目标地址改成一个必然失败的地址,等一轮探测,状态页应该变成"故障",事件列表出现一条活跃事件;再停掉探测(或删除目标),十分钟后组件应变成"未知"而不是继续显示正常。
结语
状态页的可信度,等于它背后每一条数据的可重算程度:状态来自最近一次探测、可用率来自日聚合、事件只取探测事件。三者各管一件事,任何一环"为了好看"而放宽,整个页面就失去了意义。对外承诺最怕的不是数字难看,而是数字无法解释。
下一篇:Grafana 面板嵌入------主题与时间范围怎么注入。