antithesis-query-logs

Antithesis 日志浏览器

技能版本： 2026-09-23 a8fe900

用途和目标

搜索 Antithesis 测试运行中的所有时间线，查找事件、关联属性失败，并回答有关先后顺序和因果关系的时间问题——消除级联、关联故障、测试根因假设，以及任何“如果 X 先于 Y 发生”的查询。

日志浏览器不同于用于分诊的单例日志查看器。分诊日志查看器显示以单个事件为中心的一条时间线。日志浏览器会搜索一次运行中的所有时间线，支持时间查询（先于、未先于、后于、未后于），并在多元宇宙地图上可视化结果。

适用场景

• 调查某项属性失败是独立发生，还是由更早的失败引发的级联
• 统计各时间线中某项失败的独立发生次数
• 关联失败与故障注入事件
• 比较不同后端配置之间的失败模式
• 确定失败共同发生的时间线集群

前置条件

• 如果未安装 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。用于筛除级联失败。
• 多元宇宙地图：时间线树的可视化图。失败以圆点表示。相关时间线上聚集的圆点可能表明存在共同根因。
• 独立集群数量：失败出现的不同时间线分支数量。“2 个集群中有 8 次失败”比单说“8 次失败”信息丰富得多——它能告诉你存在多少次独立复现。
• 会话 ID：每次运行都有唯一的会话 ID，用于限定所有查询。针对错误会话的查询不会返回结果。会话 ID 嵌入在编码后的搜索 URL 参数中。

重要：字段名称

日志浏览器使用单数字段名称，而非复数：

• assertion.message — 属性／断言名称（不是 assertions.message）
• assertion.status — passing 或 failing（不是 assertions.status）
• general.output_text — 日志输出文本

assertion.status 字段必须使用 matches 运算符，不能使用 contains。其他文本字段使用 contains。

会话设置

使用 agent-browser 和共享的 Antithesis 身份验证：

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

启动日志浏览器

有三种方法可以打开日志浏览器并选中正确的运行：

方法 1：从分诊报告进入（首选）

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

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

导航到返回的 URL。这会自动设置正确的会话／运行。

URL 格式如下：

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

v5v 前缀是版本标记。Base64 载荷包含查询 JSON，其中包括会话 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"

重要：搜索前务必确保已选择正确的运行。每次运行都有自己的会话 ID——针对错误会话执行的查询不会返回任何结果。所选运行会显示在页面顶部的下拉菜单中。

参考文件

参考资料	阅读时机
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，就使用它（例如，将 URL 交给 agent-browser open 或粘贴到浏览器中）。 无需注入、无需 DOM，也无需会话。

  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 时，才使用页面内运行时。

推荐工作流

级联排除

1. 获取会话 ID——可以从分诊报告的 “Explore logs”链接中提取（python3 assets/build-url.py decode --url "$EXPLORE_LOGS_URL" | jq -r .s）， 也可以从任何现有的 Logs Explorer URL 中获取。
2. 使用 Python CLI 构建简单的失败 URL：

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

3. 使用 agent-browser open 打开 URL，注入运行时，执行搜索，并通过 window.__antithesisQueryLogs.search() 读取计数。
4. 构建时间条件 URL：

   python3 assets/build-url.py not-preceded-by \
     --session-id "$SESSION_ID" --property "my-failing-property" \
     --pre-field assertion.message --pre-value "suspected-upstream-failure" \
     --tenant "{tenant}.antithesis.com"
   

5. 跳转到该 URL，执行搜索，并记录新的计数。
6. 如果计数下降，差值就是级联失败的数量。如果计数不变，说明这些失败彼此独立。

结合事件详情进行失败关联

1. 搜索属性失败
2. 展开多个结果中的 {} 详情
3. 找出各结果中有所不同的详情字段（例如配置模式、功能标志、容器名称、协议版本）
4. 留意失败是否集中在某个特定详情值上——如果所有失败都包含某个其他通过事件不具备的共同详情，那么该详情很可能是根本原因的一部分

独立集群分析

1. 搜索属性失败
2. 切换到 Map 标签页
3. 统计带有失败点的不同时间线分支数量
4. 同一分支上的失败很可能有相同的根本原因
5. 为每个集群选取一个有代表性的样本进行调查

输出

• 事件计数（匹配总数、时间筛选后的匹配数）
• 事件详情（时间戳、时间线、断言详情和自定义键值对）
• 多重宇宙映射中的集群数量
• 每次故障的日志上下文（故障事件、前序操作）