antithesis-triage

用途

Antithesis Triage 用于分析 Antithesis 测试运行（run）的结果，帮助理解一次运行中发生了什么。它面向需要排查测试失败、查看运行状态或获取运行概览的用户。

必须安装 snouty，且版本至少为 0.6.0（使用 snouty --version 查看，snouty update 更新）。
必须安装 jq。
安装说明参见 snouty 的 README：https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md
jq 下载：https://jqlang.org/download/

运行以下命令确认设置就绪：

snouty doctor --json

仅当顶层 ok 为 true 且 api_key 检查状态为 ok 时继续。否则转达失败检查的消息/备注并停止；若 api_key 失败，提示用户设置 ANTITHESIS_API_KEY。

可通过以下命令查看解析后的 tenant：

snouty doctor --json | jq -r '.settings[] | select(.name == "tenant") | .value'

Tenant 名称（必需）：从 snouty doctor --json 读取解析后的 tenant；仅当 doctor 显示 tenant 未设置时才询问用户。
用户想了解什么：所有失败、特定失败、总体概览还是比较运行，这决定后续工作流。

主要方法是使用 snouty runs <OPTION> 命令并加上 --json 选项，返回行分隔的 JSON。需要知道 RUN_ID，参见 references/run-discovery.md。

汇总近期运行：读取 references/run-discovery.md 获取近期运行列表，然后生成报告。
查找特定运行：读取 references/run-info.md，然后按需继续其他工作流。
分诊运行：若状态为 incomplete，参考诊断未完成运行部分。读取 references/run-info.md 加载运行信息；若 links.triage_report 为 null/缺失，则报告该运行不可分诊（属性和日志端点将返回 404）。读取 references/properties.md 加载属性；审查通过/失败计数；检查插桩设置信号（Software was instrumented 和 Symbols were uploaded 属性），读取 references/instrumentation.md 解读；生成详细摘要，包含所有失败审查及新增失败标记，并包含插桩状态。
调查失败属性：读取 references/properties.md，使用 snouty runs --json properties 提取属性及其示例并学习下载日志；读取 references/logs.md 理解日志。对每个要调查的属性：选择第一个失败示例；查找 moment（若反例无 moment 字段，属遥测/元属性，报告反例值作为证据并跳过后续步骤）；下载示例日志；本地分析；若不确定原因，考虑下载同一属性的其他反例和示例日志进行对比。搜索更多日志时先使用：

snouty runs --json events ${RUN_ID} ${PROPERTY_NAME}

注意这返回部分而非全部案例。将返回的 moment 与已下载的示例/反例 moment 进行比对。重要：将日志与 SUT 和工作负载源代码交叉引用。深入调查以理解导致失败的事件时间线。报告发现。注意：仅凭属性状态和断言文本不足，日志提供理解失败所需的实际运行时上下文。

验证插桩：读取 references/instrumentation.md。
诊断未完成运行：执行 snouty runs --json show ${RUN_ID}；查看 failure_moment 结构，若存在则用 input_hash 和 vtime 下载日志；尝试获取构建日志：snouty runs --json build-logs ${RUN_ID} 并查找错误。注意：对于未完成运行，属性和日志端点通常返回 404，但 links.triage_report 和 failure_moment 可能仍填充在 show 中。报告 show 实际包含的内容。

在分诊摘要末尾添加简短的“下一步”部分，列出后续技能或额外分诊工作流作为建议，由用户决定是否调用。可建议的技能包括：

包含下一个技能所需的数据（run_id、属性名、moment 等）。

完成前对照以下标准审查工作：

每个属性状态均从实际属性获取中提取，而非推断。
发现引用属性数据中的具体数据。
有日志的失败属性包含可操作上下文。
摘要区分报告显示的内容与解读或建议。
比较运行时，差异基于两个报告的数据。
声称二进制未插桩时遵循 references/instrumentation.md，不依赖去重后的 Software was instrumented 属性示例。