Skip to content

docs: 补充 CI workflow 速率预算口径与一期告警内容 #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TangJia025 merged 2 commits into from
Oct 26, 2026
Merged

docs: 补充 CI workflow 速率预算口径与一期告警内容 #39

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1211b3c
docs: 说明 CI workflow 速率预算中 21 仓的来源与口径
TangJia025 Oct 23, 2026
45cd469
docs: 新增 5.3.1 告警内容，给出失败与排队两类告警的模板和邮件样式
TangJia025 Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions docs/可观测接入指南.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -671,6 +671,103 @@ Service 端口名命中白名单即可，无需写 job。以 oauth2-proxy 为例

一期的两个适配器同步落地：GitHub 先行，GitCode 在 `Source` 接口定稿后并行接入。**契约与接口必须一次到位**——`platform` 标签、枚举归一、排序键抽象晚加等于全部序列换名。GitCode 接口实测若有阻塞，允许它的适配器在一期后段交付，但不允许先只做 GitHub 再回头改契约。

#### 5.3.1 告警内容

一期产出两类面向人的告警：**结果层**（workflow 失败）与**在途层**（排队过久）。自监控类告警（凭据失效、采集停摆等，见 5.2.3）规则形态相同，不在此重复。两条规则都在中心 Prometheus 评估，经 Alertmanager 发邮件。

**失败告警**：只对门禁类 run 逐次告警（`schedule` / `push` / `workflow_dispatch`），PR 触发的失败不逐次报——实测单个仓约 1 次失败/小时，逐次报会淹没通知，PR 作者侧 GitHub 本来就会显示红叉。

```yaml
- alert: CIWorkflowRunFailing
expr: |
increase(ci_workflow_run_result_total{
conclusion="failure",
event=~"schedule|push|workflow_dispatch"
}[5m]) > 0
for: 1m
labels:
severity: critical
cluster: central
annotations:
summary: "{{ $labels.repo }} / {{ $labels.workflow }} 执行失败"
description: >-
仓库 {{ $labels.repo }}（{{ $labels.platform }}）的 workflow「{{ $labels.workflow }}」
在最近 5 分钟内出现失败，触发方式 {{ $labels.event }}。
指标不含 run 身份，请在 GitHub Actions 里按 workflow 名查最近一次红叉。
runbook: >-
1) 打开 https://github.com/{{ $labels.repo }}/actions 按 workflow 名筛选，定位失败 run；
2) 判断是代码问题、flaky 用例还是 runner 未启动（startup_failure）；
3) 若是定时/主干门禁连续失败，先恢复 main，再复盘。
```

用户收到的邮件（时延约 1～2 分钟）：

> **主题**：`[CRITICAL][central] CIWorkflowRunFailing`
>
> **🔴 FIRING — CIWorkflowRunFailing @ central**
>
> | 字段 | 内容 |
> | --- | --- |
> | 集群 | central |
> | 告警 | CIWorkflowRunFailing |
> | 状态 | firing |
> | 开始时间 | 2026-10-26 09:12:33 CST |
> | 描述 | 仓库 vllm-project/vllm-ascend（github）的 workflow「Main2Main」在最近 5 分钟内出现失败，触发方式 schedule。指标不含 run 身份，请在 GitHub Actions 里按 workflow 名查最近一次红叉。 |
>
> **修复建议**
>
> 1) 打开 https://github.com/vllm-project/vllm-ascend/actions 按 workflow 名筛选，定位失败 run；2) 判断是代码问题、flaky 用例还是 runner 未启动（startup_failure）；3) 若是定时/主干门禁连续失败，先恢复 main，再复盘。
>
> `Alertmanager | 监控看板 | 本邮件由 CI 基础设施监控系统自动发送，请勿回复。`

恢复后再发一封，主题变 `[RESOLVED][central] CIWorkflowRunFailing`，正文标题变 `✅ RESOLVED`，并多一行「恢复时间」。

**排队过久告警**：告警对象是仓库，不是单个 run——指标按仓聚合，取的是该仓最久的排队时长。

```yaml
- alert: CIWorkflowQueueBacklog
expr: ci_workflow_oldest_queued_age_seconds > 1800
for: 10m
labels:
severity: critical # 定 warning 会被中心黑洞吞掉，见下文「模板约束」
cluster: central
annotations:
summary: "{{ $labels.repo }} 有 run 排队超过 30 分钟"
description: >-
仓库 {{ $labels.repo }}（{{ $labels.platform }}）队列积压：最久的 run 已等待
{{ $value | humanizeDuration }}。常见原因是仓库并发上限已满或 runner 池没有空闲机器。
runbook: >-
1) 看同仓 runs_queued 是否持续上涨；
2) 查 ARC 对应 scale set 的 desired/running runner 是否卡在 0；
3) 若是长期排队而非故障，考虑调高该仓 concurrency 或扩卡池。
```

用户收到的邮件（时延约 7 分钟：B 路径 5 分钟轮询 + 抓取 + 评估）：

> **主题**：`[CRITICAL][central] CIWorkflowQueueBacklog`
>
> **🔴 FIRING — CIWorkflowQueueBacklog @ central**
>
> | 字段 | 内容 |
> | --- | --- |
> | 集群 | central |
> | 告警 | CIWorkflowQueueBacklog |
> | 状态 | firing |
> | 开始时间 | 2026-10-26 10:28:10 CST |
> | 描述 | 仓库 vllm-project/vllm-ascend（github）队列积压：最久的 run 已等待 47m0s。常见原因是仓库并发上限已满或 runner 池没有空闲机器。 |
>
> **修复建议**
>
> 1) 看同仓 runs_queued 是否持续上涨；2) 查 ARC 对应 scale set 的 desired/running runner 是否卡在 0；3) 若是长期排队而非故障，考虑调高该仓 concurrency 或扩卡池。

**模板约束**（中心 Alertmanager 现有 `email.infra.html`，接入前必须处理）：

- **`cluster` 标签不能缺**。主题模板是 `[{{ severity }}][{{ cluster }}] {{ alertname }}`，正文标题是 `@ {{ cluster 或 project }}`；两者都没有时会渲染成 `[CRITICAL][] …` 和 `@ `。规则里显式写 `labels: cluster: central`，或给 CI 告警单独一个 receiver 改用 `{{ or .CommonLabels.cluster .CommonLabels.repo }}`（`datastat-email` 已是这种写法）。
- **`severity: warning` 默认被黑洞丢弃**（路由树在 warning 之前没有 CI 前缀规则）。新告警要么定为 critical，要么在黑洞之前补 `alertname =~ "CIWorkflow.*"` 的路由。
- **`repo` / `workflow` / `platform` 不会出现在表格里**：模板只渲染 `cluster` / `project` / `pod` / `node` / `instance` / `deployment` / `mount` / `endpoint`。要么把定位信息写进 `description`（上面两条就是这么做的），要么给模板加「仓库 / Workflow / 平台」三行。
- **`runbook` 必填**：模板的「修复建议」表直接引用 `.Annotations.runbook`，缺了就是一格空白。
- **`group_by` 要加维度**：根路由是 `[cluster, alertname]`，同一仓多个 workflow 失败会被并进同一封（`group_interval` 30 分钟）；需要按 workflow 分开时，在 CI 路由里改为 `[platform, repo, workflow, alertname]`。

### 5.4 详细设计

#### 5.4.1 中心 aggregator
Expand Down Expand Up @@ -788,6 +885,15 @@ B+ 的调用量随活跃 run 数走（20~40 个 × 12 次/小时 ≈ 240~480 次
| B+ | 20~40 个活跃 run × 12 | 240~480 |
| 合计 | | **约 2,000~2,250（45%）** |

表中「21 仓」是**开通了 ARC runner 的仓库数**，不是集群数也不是 scale set 数：它取自
`opensourceways/ascend-ci-deployment` 仓 `projects/<org>/<repo>/` 下存在 `values.yaml` 的目录，
按 `<org>/<repo>` 去重（一个仓可以有多个 scale set，只算一次），快照于该仓 commit `26ca84d1`（2026-10-20）。
集群文档站的 [Cluster Map](https://ascend-gha-runners.github.io/docs/Cluster/) 由同一份部署配置自动生成，
页面上标注的「21 Projects」与此一致，可用来交叉核对；部署新增仓库时按实际仓数线性重算这张表。

其余系数：A 的 60 = 每分钟一轮 × 60 分钟；B 的 12 = 每 5 分钟一轮 × 12，两条列表指 `queued` 与 `in_progress`；
B+ 的 12 同理，基数是该时刻在途的 run 数（实测 20~40）。

GitCode 的限流规则未公开，接入前要实测；适配器里要有独立的配额余量指标。

**两个适配器的差异**
Expand Down
Loading