Ray 项目 Buildkite CI 日志获取与分析实战指南

Ray 项目 Buildkite CI 日志获取与分析实战指南【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray导读本指南以 Ray 仓库内置的 Claude Code 技能Skillfetch-buildkite-logs 为核心系统讲解如何通过 Buildkite REST API 从一条构建 URL或构建号出发依次完成构建解析 → 失败任务定位 → 单任务日志抓取 → ANSI 清理 → 失败归因并在日志不足以定位根因时继续深入任务的 Artifacts构建产物挖掘更多日志。读完本文你将掌握一套可直接复制运行的 Shell Python 命令组合能够独立完成 Ray CI 失败日志的自动化拉取与初步诊断并了解其中涉及的 Token 权限、分页、HTTP 重定向等关键细节。该技能是 Ray 仓库为 AI 编程助手配置的共享技能之一相关使用说明与 Token 申请流程记录在 agent-development.md 中仓库内 CI 自动化代码如 release/ray_release/buildkite 目录也大量基于 Buildkite 构建体系运行本指南可视为该体系的日志侧配套操作手册。一、前置条件Buildkite API Token技能的第一步不是任何 curl 命令而是确认环境变量BUILDKITE_API_TOKEN已配置[ -n $BUILDKITE_API_TOKEN ] echo token set || echo token MISSING注意验证时绝不能把 Token 本身回显出来任何会打印秘密字符的命令都会被拦截这是 Ray 团队在技能定义中明确的硬性安全约束。Token 的申请与权限范围Token 的完整申请流程记录在仓库文档 doc/source/ray-contribute/agent-development.md 中核心要点如下在 Buildkite 的「API Access Tokens」页面新建 Token勾选以下三个权限范围Scoperead_builds—— 读取构建与任务元数据read_build_logs—— 读取任务日志read_artifacts—— 读取构建产物仅在需要进一步翻 Artifacts 排查时必需将 Token 写入 Shell 配置文件并重载# Add to ~/.bashrc or ~/.zshrc export BUILDKITE_API_TOKENyour-token-here source ~/.bashrc缺少read_artifacts时Artifacts 相关接口会直接返回HTTP 403这是技能文档明确点出的常见坑能拉日志但拉不了产物多半是权限范围没勾全。二、解析 Buildkite URL提取 pipeline 与 build numberBuildkite 构建 URL 的标准形态为https://buildkite.com/ray-project/PIPELINE/builds/BUILD_NUM#JOB_ID从 URL 中必须提取两个要素PIPELINE流水线名例如premerge合入前、postmerge合入后。技能明确警告不能硬编码premerge——同一技能服务于所有流水线从 URL 动态提取才是正确做法BUILD_NUM构建号。URL 中的#JOB_ID片段fragment指向的是一个真实存在的具体任务而非 group/wait 这类聚合任务存在时可以直接对该任务发起查询不存在时则需先通过构建信息枚举出失败/异常的任务。三、分步拉取日志从构建到任务的完整调用链技能将整个流程收敛为 7 个步骤命令全部面向 Buildkite v2 REST API组织方式为 Ray 官方流水线所属组织ray-project。1. 获取构建信息curl -s -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM返回的 JSON 中jobs数组携带该构建下所有任务的状态信息是后续所有定位动作的数据源。2. 有 JOB_ID直接查询目标任务当 URL 带#JOB_ID时直接从jobs中按id精确匹配curl -s -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM \ | python3 -c import sys,json; jobsjson.load(sys.stdin)[jobs]; [print(f\{j[id]} {j.get(name)} - {j.get(state)}\) for j in jobs if j[id]JOB_ID]3. 无 JOB_ID枚举失败/异常任务没有任务片段时先筛选出failed与broken状态的任务再逐个深入curl -s -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM \ | python3 -c import sys,json; jobsjson.load(sys.stdin)[jobs]; [print(f\{j[id]} {j.get(name)} - {j[state]}\) for j in jobs if j.get(state) in (failed,broken)]输出形如任务ID 任务名 - 状态据此挑出需要深挖的任务。4. 拉取单个任务日志curl -s -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM/jobs/JOB_ID/log \ /tmp/log_JOB_ID.json5. 清理 ANSI 转义序列Buildkite 日志接口返回的是 JSON日志正文在content字段中且含有大量 ANSI 转义码用于终端着色。直接 grep 会得到满屏噪音必须先用正则剥离re.sub(r\x1b\[[0-9;]*m, , content)即匹配\x1b[开头的 CSI 序列\x1b[31m之类的颜色码并将其移除得到纯文本后即可用grep、tail等工具定位失败栈。6. 归纳失败原因并给出修复建议对清理后的日志聚焦关键信号测试断言、异常堆栈、超时、OOM 等并结合任务名如对应哪个测试文件归纳根因。这也与仓库内 CI 测试判定逻辑如 ci/pipeline/check-test-run.py、ci/pipeline/determine_tests_to_run.py 中对测试状态的分类思路相互印证。四、深入 Artifacts当日志不足以定位根因时很多时候任务日志只给出测试挂了的入口真正的根因如死锁栈、Core dump、覆盖率报告散落在任务的 Artifacts 里。技能的 Artifacts 章节给出完整翻查流程。1. 列出任务的 Artifacts注意分页curl -s -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM/jobs/JOB_ID/artifacts?per_page100page1接口默认分页当返回满 100 条时就要递增page参数继续翻页否则会遗漏产物。2. 按 id 下载指定 Artifactcurl -fsL -H Authorization: Bearer $BUILDKITE_API_TOKEN \ https://api.buildkite.com/v2/organizations/ray-project/pipelines/PIPELINE/builds/BUILD_NUM/jobs/JOB_ID/artifacts/ARTIFACT_ID/download \ -o /tmp/ARTIFACT_ID这里有两个容易被忽略的细节技能文档特别强调-L必不可少下载接口返回HTTP 302并重定向到 S3 预签名地址-L负责跟随重定向跨主机跳转时 Authorization 头会被 curl 丢弃这是期望行为——S3 只认预签名 URL若强行把 Bearer 头带过去反而会触发400 InvalidRequest。因此保持默认行为即可无需追加--location-trusted之类的参数。3. 解压 zip 产物循环排查若下载到的 Artifact 是 zip 包日志通常封装在包内解压后继续检索仍不足以定位根因时就换下一个 Artifact 重复上述流程直到找到可解释失败证据的日志为止。五、认证故障排查技能最后给出一个高频认证报错的处置口径若curl返回{message:No organization found}说明当前 Token 无权访问ray-project组织需要更换 Token用户手中可能持有其他组织维度org-scoped的 Token此时应主动询问用户应 source 哪个环境变量而不是臆断。这类组织级权限问题在大型组织Ray 有多个内部流水线中很常见排查时要先确认 Token 归属组织与请求 URL 中的组织名一致。六、技能在整个 Agent 工作流中的定位fetch-buildkite-logs是 Ray 仓库 .claude/skills 目录下五个共享技能之一其余还包括/rebuild基于改动文件引导重建、/lint运行 lint 与格式检查、/backport-docs将已合并文档 cherry-pick 到发布分支与ray-dependencies。它们在 Claude Code 中以/skill-name形式按需加载而本技能与仓库文档 agent-development.md 中「Using agents for development」的配置体系直接配套——从 Token 申请、个人环境配置CLAUDE.local.md到规则/技能的组织方式形成一套完整的 AI 辅助开发闭环。实践中Agent 处理 CI 失败类问题的典型路径为用户给出 Buildkite URL → 技能解析 pipeline 与 build → 枚举失败任务 → 拉日志并清理 ANSI → 归纳失败 → 必要时翻 Artifacts 深挖 → 给出修复建议并最终落地为代码改动再交由/rebuild、/lint验证。这也解释了为什么 Ray 仓库在 release/ray_release/buildkite 等目录中沉淀了大量与 Buildkite 流水线交互的自动化代码——CI 日志的获取与分析是整个发布/测试体系的可观测性底座。小结Token 先行BUILDKITE_API_TOKEN必须就位且按需授予read_builds、read_build_logs、read_artifacts三个 scope验证时严禁回显 Token动态解析pipeline 与 build number 一律取自 URL禁止硬编码premerge分层深入构建级枚举失败任务 → 任务级拉取日志 → 剥离 ANSI 后 grep → 日志不足再下探 Artifacts注意分页、-L跟随 302、跨主机丢弃 Authorization 头报错有口径No organization found指向 Token 组织权限问题应切换组织级 Token。把这套命令链沉淀为可复用的排查流程配合 Ray 仓库的 Agent 开发体系即可把CI 红了这类问题从人工点网页、翻日志的苦差事变成可批量、可复现、可自动化的一键式诊断。【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考