PyTorch CI 指标查询实战：从 Grafana gcx 封装脚本到 ClickHouse 与 Prometheus 查询

PyTorch CI 指标查询实战从 Grafana gcx 封装脚本到 ClickHouse 与 Prometheus 查询【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch本文以 PyTorch 仓库中的 CI 指标查询技能文档 SKILL.md 为主体完整讲解如何通过 gcx-wrapper.sh 封装脚本访问 PyTorch 的 Grafana 实例查询 CI 时长、任务失败、队列深度、workflow 趋势与 Runner 健康状况等指标并覆盖其依赖的 ClickHouse 数据表结构与 Prometheus 指标模型帮助读者以及 CI 诊断类 Agent掌握 PyTorch 基础设施数据的完整查询路径。一、技能定位CI 指标查询解决什么问题PyTorch 的 CI 与基础设施指标通过 Grafana 暴露。当 oncall 工程师需要回答“最近两周 main 分支上哪些 workflow job 失败最多”“某个测试文件上周跑了多少次、通过率和失败率如何”“当前哪类 Runner 队列最深”这类问题时PyTorch 仓库在.claude/skills/ci-metrics/目录下提供了一个专门面向 CI 指标查询的技能其元信息声明了明确的触发场景查询 CI 时长、任务失败、排队时间、workflow 趋势、Runner 健康度、Dashboard 数据或 PyTorch 基础设施指标时使用。该技能目录包含两个文件SKILL.md技能说明文档定义数据源、表结构与示例查询gcx-wrapper.sh所有 Grafana 访问的统一入口脚本负责配置 PyTorch 的 Grafana 服务器、上下文与认证。一个关键权限约束需要注意只有对仓库具有写权限的用户才能访问 Grafana且认证下发的 token 仅提供只读访问。这意味着该通道适合只读诊断不能通过它修改 Dashboard 或数据。二、依赖要求与 gcx-wrapper.sh 的自动化机制2.1 运行前提封装脚本要求 PATH 中存在两个工具gh用于获取 Grafana token且必须已完成认证。若未认证文档给出的修复命令是gh auth login --hostname github.com --git-protocol ssh --webcurl用于下载gcx二进制以及从 HUD 拉取 token。首次使用时封装脚本会下载一个固定版本pinned且经过校验和验证的gcx二进制放入私有缓存目录~/.cache/pytorch-ci-metrics/并自动完成认证。整个过程不会向用户的 PATH 安装任何东西。如果缺少工具或gh未认证脚本会退出并给出描述性错误信息。2.2 源码级机制拆解阅读 gcx-wrapper.sh 可以看到文档描述背后的具体实现服务器与上下文均可被环境变量覆盖默认值为GCX_SERVERhttps://pytorchci.grafana.net、GCX_CONTEXTpytorchci第 5-6 行gcx版本被固定在GCX_VERSION0.4.3二进制缓存路径为${XDG_CACHE_HOME:-$HOME/.cache}/pytorch-ci-metrics/gcx-${GCX_VERSION}第 11-13 行。_ensure_gcx函数通过官方安装脚本下载到临时目录并在成功产出二进制后移动到缓存位置第 20-39 行注释明确说明 gcx 安装器会验证下载的 SHA-256 校验和这正是文档中“checksum-verified”的来源。认证流程由_login_gcx函数实现第 45-77 行调用链为检查gh存在并用gh auth status确认已认证通过gh auth token读取 GitHub token用该 token 请求 HUD 的接口https://hud.pytorch.org/api/gcx-token?token_name$HOSTNAME换取 gcx token以主机名区分 token 身份调用gcx login pytorchci --server ... --yes --token ...完成登录。脚本入口处的逻辑第 79-92 行是先确保 gcx 已就位再通过gcx api /api/health做健康检查健康检查失败才触发登录流程登录成功后执行gcx config use-context切换上下文最后用exec透传用户参数——这使得封装脚本对gcx子命令完全透明例如gcx-wrapper.sh datasources ...等价于对配置好的 PyTorch 上下文执行gcx datasources ...。三、数据源总览datasources list查看所有可用数据源的命令是.claude/skills/ci-metrics/gcx-wrapper.sh datasources list技能文档特别指出这些数据包含 PyTorch 体系内多个仓库的指标查询时尽量把范围限制在pytorch/pytorch仓库对应查询条件repository_full_name pytorch/pytorch。两类核心数据源数据源用途查询方式grafana-clickhouse-datasourceCI 与测试运行数据GitHub webhook 事件、每次测试运行明细ClickHouse SQLgrafanacloud-pytorchci-promCI 基础设施指标Runner 队列、集群负载等PromQL四、ClickHouse 侧CI 与测试运行数据4.1 表结构列出数据源下所有可用表.claude/skills/ci-metrics/gcx-wrapper.sh datasources clickhouse list-tables文档列出的重要数据集如下GitHub webhook 数据数据库default注意default数据库中还包含其他与 webhook 无关的表查询时不要假设该库只有 webhook 数据。典型表如default.workflow_job其事件与 payload 语义遵循 GitHub 官方 webhook 事件规范。测试运行数据数据库teststests.all_test_runs包含每一次测试运行是极其庞大的表查询时必须注意过滤条件与执行时长避免全表扫描。不要使用tests.test_run_s3它只包含部分数据。文档还建议如需更多常见查询范式可以把pytorch/test-infra仓库克隆到临时目录阅读其中torchci文件夹。4.2 实战查询一main 分支上失败最多的 workflow job统计pytorch/pytorch仓库 main 分支最近两周内失败次数最多的 workflow job按 job 名称去重计数.claude/skills/ci-metrics/gcx-wrapper.sh datasources clickhouse query SELECT name, count(DISTINCT id) AS failures FROM default.workflow_job WHERE conclusion failure AND completed_at now() - INTERVAL 2 WEEK AND repository_full_name pytorch/pytorch AND head_branch main GROUP BY name ORDER BY failures DESC LIMIT 10字段含义name为 workflow job 名称id为 job 运行标识用count(DISTINCT id)避免重复行虚增计数conclusion failure筛选失败结论completed_at限定时间窗repository_full_name与head_branch实现文档要求的“限制到 pytorch/pytorch 的 main 分支”。查询结果可以直接指导 oncall 定位哪些 job 是当前的失败热点——例如对照仓库 .github/workflows/ 中的 workflow 定义文件如_linux-build.yml、_lint.yml等进一步缩小排查范围。4.3 实战查询二某测试文件一周内的运行与通过情况以文件lazy/test_ts_opinfo.py对应仓库中的 test/lazy/test_ts_opinfo.py为例统计最近一周内每个测试用例的运行次数、成功数、失败数与跳过数.claude/skills/ci-metrics/gcx-wrapper.sh datasources clickhouse query SELECT file, classname, name, count() AS runs, countIf(failure_count 0 AND error_count 0 AND skipped_count 0) AS successful, countIf(failure_count 0 OR error_count 0) AS fails, countIf(skipped_count 0) AS skipped FROM tests.all_test_runs WHERE time_inserted now() - INTERVAL 7 DAY AND file lazy/test_ts_opinfo.py GROUP BY file, classname, name ORDER BY runs DESC要点说明file、classname、name三个字段构成一次测试运行的定位键测试文件、用例所属类、用例名与 PyTorch 测试目录的组织方式一致例如test/lazy/test_ts_opinfo.py中的 opinfo 类用例成功判定同时要求failure_count 0 AND error_count 0 AND skipped_count 0即跳过不计入成功时间过滤使用time_inserted数据入库时间而非测试执行时间查询时需注意该语义差异由于tests.all_test_runs极大file ...这类等值过滤条件务必保留避免大表全扫。五、Prometheus 侧CI 基础设施指标基础设施指标存储在grafanacloud-pytorchci-prom。为理解底层指标是如何导出的文档建议参考pytorch/ci-infra仓库的/osdc目录OSDC 是承载 PyTorch CI 的基础设施代码其docs说明了项目范围与配置以及actions-runner-controller相关仓库理解 Runner 控制器如何暴露数据。从源码结构看指标名以gha_GitHub Actions为前缀按nameRunner 类型与cluster维度聚合。5.1 查询当前队列最深的 Runner 类型“队列深度”定义为已分配但尚未运行的任务数即gha_assigned_jobs - gha_running_jobs用clamp_min(..., 0)防止负值再取 Top 10.claude/skills/ci-metrics/gcx-wrapper.sh datasources prometheus query -d grafanacloud-prom topk(10, clamp_min(sum by (name) (gha_assigned_jobs) - sum by (name) (gha_running_jobs), 0))-d grafanacloud-prom指定 Prometheus 数据源别名该即时查询返回的是“此刻”哪类 Runner 积压最严重是排查 CI 排队变慢的第一入口。5.2 范围查询各集群近 6 小时运行中的任务数使用--since/--step或--from/--to发起范围查询按 30 分钟采样.claude/skills/ci-metrics/gcx-wrapper.sh datasources prometheus query -d grafanacloud-prom sum by (cluster) (gha_running_jobs) --since 6h --step 30m这条查询可以观察各集群的负载随时间的变化趋势与队列深度查询结合即可区分“容量不足”长期高位与“瞬时尖峰”短时冲高两类问题。六、与仓库内 HUD 工具的关系HUDhud.pytorch.org是 PyTorch CI 的可视化面板与本技能共享同一套 CI 数据。仓库内已有配套工具 scripts/hud/analyze_failing_jobs.py它是一个供 pt2 oncall 手工运行的只读统计工具拉取 HUD 背后的近期 job 网格找出处于失败连击failure streak中的 job输出连击长度、整体失败率、开始失败的时间点以及不同的失败签名。从该脚本的文档字符串看它直接消费 HUD 的公开 APIhttps://hud.pytorch.org/api/hud/pytorch/pytorch并且需要设置HUD_INTERNAL_BOT_TOKEN环境变量以通过前端 WAF 的匿名流量拦截它与本文的 gcx-wrapper 通道互补——前者面向“某分支/提交上哪些 job 正在持续失败”的连击分析后者面向更自由的 ClickHouse SQL 与 PromQL 指标查询。七、使用注意事项小结权限只有对 PyTorch 仓库有写权限的用户可访问 Grafanatoken 只读任何查询都只能读数据。认证gh必须已登录HUD 换 token 接口会拒绝未认证的请求失败时脚本会给出具体修复命令。大表纪律tests.all_test_runs极大查询必须带时间范围与等值过滤tests.test_run_s3数据不完整禁止用于结论性统计。仓库范围数据覆盖 PyTorch 体系内多个仓库聚合类查询应始终限定repository_full_name pytorch/pytorch除非有意做跨仓库对比。零安装副作用gcx 二进制固定在 0.4.3 版本并缓存在私有目录不污染 PATH缓存损坏时可删除~/.cache/pytorch-ci-metrics/下的旧二进制让其重新下载。八、小结.claude/skills/ci-metrics/技能用一份 96 行的文档加一个 92 行的 bash 封装把“查询 PyTorch CI 指标”收敛为单一入口gcx-wrapper.sh自动处理 gcx 下载、校验、认证与上下文切换使用者只需关心两类查询——ClickHouse SQLdefault.workflow_job管 CI job 运行事件tests.all_test_runs管逐条测试运行与 PromQLgha_assigned_jobs/gha_running_jobs等基础设施指标。配合 scripts/hud/analyze_failing_jobs.py 的连击分析构成了 PyTorch 仓库内一套完整、只读、可脚本化的 CI 健康诊断工具链。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考