[TangJia025]

接入指南第 5 章整体重写：从「只有结果观测」扩展为覆盖 GitHub + GitCode 的 CI workflow 完整观测方案。

Resolves https://github.com/opensourceways/backlog/issues/2061

整体架构

三个组件、两条通路：

• 中心 ci-workflow-aggregator（单副本）：轮询 REST API，产出 run/job 级指标，暴露 /metrics；
• 各集群 ghalistener（已有 387 个）：容量 gauge 与 ③④ 耗时，经集群 Prometheus agent remote_write 进中心；
• 各集群 ci-event-agent（三期）：watch EphemeralRunner，把 job 级事件 POST /ingest 给 aggregator。

架构图按 CI 集群在上、中心集群在下重画，事件上报与 remote_write 落到不同组件，避免被读成一条路。

指标与阶段

• 结果/耗时、在途状态、自监控、集群侧容量四组指标，全部带 platform 标签；
• 阶段切成 ① 平台排队 / ② 扩容 / ③ 启动 / ④ 执行，用于分诊；
• 明确 ② 和 ③ 在 ARC 指标里拆不开（listener 只有一条 startup 直方图），二期 B 买到的是 ②+③ 合计，不是分段。原文按「可拆分」描述，已修正。

双平台

• GitHub 与 GitCode 共用一套 aggregator，取数层抽成 Source 接口（ListRuns / GetRun / ListJobs）；
• 状态与结论归一：GitHub 是 status + conclusion 两个字段，GitCode 只有一个 status，适配器负责拆开并映射成统一取值；
• 排序键抽象掉 created_at（GitCode 没有该字段，用 start_time）；
• 一期就落两个适配器：契约与接口一次到位，后加标签等于全部序列换名。

分期

期次	组件	观测能力
一期	aggregator（两个适配器 + 终态/在途/job 轮询 + 截断守卫 + 指标告警大盘）	run/job 结果与耗时、在途排队与执行、失败率与连续失败
二期	Prometheus agent 加 scrape job（A 步）→ listenerMetrics 声明（B 步）	先容量 gauge，再补启动/执行耗时与 job 级排队
三期	各集群 event agent	run 身份、重跑补齐、精确完成事件

详细设计见第 5.4 节（aggregator / ghalistener / event agent 的内部结构、三条轮询路径、去重与剪枝、核心流程），已知边界见 5.5。

🤖 Generated with Claude Code

AI 使用声明

当前 PR 是否有 AI 参与：

• 否
• 是
  1. AI Agent 平台：Claude Code
  2. AI 模型：deepseek-v4-flash
  3. Prompt 上下文：梳理 CI workflow 观测方案（架构、指标、分期、双平台归一），重写可观测接入指南第 5 章

[opensourceways-bot]

Welcome To opensourceways Community

Hey @TangJia025 , thanks for your contribution to the community.

Bot Usage Manual

I'm the Bot here serving you. You can find the instructions on how to interact with me at Here . That means you can comment below every pull request or issue to trigger Bot Commands.

Contact Guide

If you have any questions, please contact the SIG: infratructure ,
and any of the maintainers: @GeorgeCao-hw, @TangJia025, @pkking, @zhongjun2 ,
and any of the committers: @GeorgeCao-hw, @TangJia025, @pkking, @zkhzkhz .

[opensourceways-bot]

CLA Signature Pass

TangJia025, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

Linking Issue Notice

@TangJia025 , the pull request must be linked to at least one issue.
If an issue has already been linked, but the needs-issue label remains, you can remove the label by commenting /check-issue .

[TangJia025]

/check-issue