企业官网建设流程全解析

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 --web；
• curl：用于下载gcx二进制以及从 HUD 拉取 token。

首次使用时，封装脚本会下载一个固定版本（pinned）且经过校验和验证的gcx二进制，放入私有缓存目录~/.cache/pytorch-ci-metrics/，并自动完成认证。整个过程不会向用户的 PATH 安装任何东西。如果缺少工具或gh未认证，脚本会退出并给出描述性错误信息。

2.2 源码级机制拆解

阅读 gcx-wrapper.sh 可以看到文档描述背后的具体实现：

• 服务器与上下文均可被环境变量覆盖，默认值为GCX_SERVER=https://pytorchci.grafana.net、GCX_CONTEXT=pytorchci（第 5-6 行）；
• gcx版本被固定在GCX_VERSION=0.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 行），调用链为：

1. 检查gh存在，并用gh auth status确认已认证；
2. 通过gh auth token读取 GitHub token；
3. 用该 token 请求 HUD 的接口https://hud.pytorch.org/api/gcx-token?token_name=$HOSTNAME换取 gcx token（以主机名区分 token 身份）；
4. 调用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'）。

两类核心数据源：

四、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 事件规范。
• 测试运行数据
  • 数据库：tests
  • tests.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）为前缀，按name（Runner 类型）与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 工具的关系

HUD（hud.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 指标查询。

七、使用注意事项小结

1. 权限：只有对 PyTorch 仓库有写权限的用户可访问 Grafana；token 只读，任何查询都只能读数据。
2. 认证：gh必须已登录；HUD 换 token 接口会拒绝未认证的请求，失败时脚本会给出具体修复命令。
3. 大表纪律：tests.all_test_runs极大，查询必须带时间范围与等值过滤；tests.test_run_s3数据不完整，禁止用于结论性统计。
4. 仓库范围：数据覆盖 PyTorch 体系内多个仓库，聚合类查询应始终限定repository_full_name = 'pytorch/pytorch'，除非有意做跨仓库对比。
5. 零安装副作用：gcx 二进制固定在 0.4.3 版本并缓存在私有目录，不污染 PATH；缓存损坏时可删除~/.cache/pytorch-ci-metrics/下的旧二进制让其重新下载。

八、小结

.claude/skills/ci-metrics/技能用一份 96 行的文档加一个 92 行的 bash 封装，把“查询 PyTorch CI 指标”收敛为单一入口：gcx-wrapper.sh自动处理 gcx 下载、校验、认证与上下文切换，使用者只需关心两类查询——ClickHouse SQL（default.workflow_job管 CI job 运行事件，tests.all_test_runs管逐条测试运行）与 PromQL（gha_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