antithesis-query-logs

用途

Antithesis Logs Explorer 技能用于在 Antithesis 测试运行的所有时间线中搜索事件、关联属性失败，并回答关于顺序与因果的时间性问题，包括级联消除、故障关联、根因假设验证，以及任何“X 是否发生在 Y 之前”的查询。

Logs Explorer 与 triage 中使用的单示例日志查看器不同：triage 日志查看器显示以单个事件为中心的一条时间线；Logs Explorer 搜索一次运行中的所有时间线，支持时间查询（preceded by、not preceded by、followed by、not followed by），并在 multiverse map 上可视化结果。

适用场景

调查某个属性失败是独立的，还是由更早失败引发的级联
统计失败在各时间线上有多少个独立发生次数
将失败与故障注入事件关联
比较不同后端配置之间的失败模式
识别失败共同出现的时间线簇

前置条件

必须已安装 snouty，安装选项见 https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md
必须已安装 agent-browser，安装选项见 https://raw.githubusercontent.com/vercel-labs/agent-browser/refs/heads/main/README.md
agent-browser 版本不得低于 v0.23.4，可用 agent-browser upgrade 升级
必须已安装 jq，安装选项见 https://jqlang.org/download/
python3（>= 3.10，仅标准库）用于 assets/build-url.py
需要一个已完成的 Antithesis 运行。如果没有具体运行 URL，先使用 antithesis-triage 技能的运行发现工作流查找
agent-browser 已安装并已通过 Antithesis 租户认证

关键概念

时间查询：搜索事件 X 是否（或不是）由事件 Y 前置或后置。用于过滤级联失败。
Multiverse map：时间线树的可视化。失败显示为点。相关时间线上的点簇暗示共享根因。
独立簇计数：失败出现的不同时间线分支数量。“2 个簇中有 8 次失败”比仅“8 次失败”信息量大得多，它说明存在多少个独立复现。
Session ID：每次运行有唯一的 session ID，限定所有查询范围。对错误 session 的查询返回空结果。session ID 嵌入在编码后的搜索 URL 参数中。

重要：字段名

Logs Explorer 使用单数字段名，而非复数：

assertion.message — 属性/断言名称（不是 assertions.message）
assertion.status — 通过或失败（不是 assertions.status）
general.output_text — 日志输出文本

assertion.status 字段需要 matches 操作符，而非 contains。其他文本字段使用 contains。

Session 设置

使用 agent-browser 配合共享的 Antithesis 认证：

SESSION="logs-explorer-$(date +%s)-$$"
agent-browser --session "$SESSION" --session-name antithesis --profile antithesis --args "--no-sandbox"

启动 Logs Explorer

有三种方式在选中正确运行的情况下进入 Logs Explorer：

方法 1：从 triage 报告（首选）

先导航到 triage 报告，然后提取“Explore logs”链接。这是最可靠的方法，因为链接中已编码了正确的 session ID。

agent-browser --session "$SESSION" eval \
  "document.querySelector('a.an-button[href*=\"/search\"]').href"

导航到返回的 URL。这会自动设置正确的 session/run。

URL 形式为：

https://{tenant}.antithesis.com/search?search=v5v{base64_encoded_query}

v5v 前缀是版本标记。base64 载荷包含查询 JSON，其中包括 session ID（s 字段）。完整查询 JSON 格式见 references/query-builder.md。

方法 2：直接从 Logs Explorer

Logs Explorer 页面顶部有“Show me logs from”下拉框（div.select_container.event_search_run_selector）。点击它可看到最近运行列表，包含名称、状态（In progress / Completed / Incomplete）和时间戳。选择所需的运行。

如果预期看到的运行缺失，刷新页面。

方法 3：从侧边栏

点击左侧边栏导航中的“Logs explorer”。这会直接进入 https://{tenant}.antithesis.com/search，未预选运行。然后使用“Show me logs from”下拉框选择运行。

agent-browser --session "$SESSION" open "https://{tenant}.antithesis.com/search"

重要：搜索前始终确保选中正确的运行。每次运行有自己的 session ID——对错误 session 的查询返回空结果。所选运行显示在页面顶部的下拉框中。

参考文件

references/query-builder.md — 构建和执行搜索查询时阅读
references/temporal-queries.md — 使用 preceded-by / not-preceded-by 过滤器时阅读
references/results.md — 阅读搜索结果并点击进入详情时阅读
references/map.md — 使用 multiverse map 进行簇分析时阅读

URL 构建（首选）与运行时注入

本技能附带两个资产。根据当前步骤选择合适的一个：

assets/build-url.py — 独立 Python CLI。无需浏览器即可构建和解码 Logs Explorer URL。任何时候只需要一个 URL（例如交给 agent-browser open 或粘贴到浏览器）时使用。无需注入、无需 DOM、无需 session。

python3 assets/build-url.py failure \
  --session-id "$SESSION_ID" \
  --property "my-failing-property" \
  --tenant "{tenant}.antithesis.com"

所有子命令（failure、not-preceded-by、not-followed-by、custom、decode）见 references/query-builder.md。

assets/antithesis-query-logs.js — 页面内运行时。仅在需要与页面交互时注入到 Logs Explorer 页面：点击 Search、等待结果、读取计数/结果行、切换到 Map 视图等。纯 URL 构建不需要运行时。

cat assets/antithesis-query-logs.js \
  | agent-browser --session "$SESSION" eval --stdin

运行时注册 window.__antithesisQueryLogs。如果对其调用时出现 TypeError: Cannot read properties of undefined，说明运行时尚未注入当前页面——先注入。

只要需要 URL，优先使用 build-url.py。仅在确实需要操作 DOM 的步骤才使用页面内运行时。

输出

事件计数（总匹配数、时间过滤后的匹配数）
事件详情（时间戳、时间线、断言详情和自定义键值对）
来自 multiverse map 的簇计数
每次失败周围的日志上下文（故障事件、前置操作）

技能介绍

用途