antithesis-debug

Antithesis Debug

スキルのバージョン： 2026-10-21 4f8d80b

実行中のある時点で bash スクリプトを実行します。呼び出すたびにマルチバースが分岐し、同じ時点から繰り返し呼び出すと同じ結果が再現されます。現在実行中のラン、またはアクティブな MVD セッションを使用できます。

このスキルを使う場合

• ユーザーから Antithesis のデバッグセッションのラン ID または URL が提示された場合
• 過去のランで失敗したプロパティ、バグ、または何らかの結果をデバッグまたは調査するよう依頼された場合
• Antithesis 内のコンテナのファイルシステム、実行時の状態、またはイベントを調べるよう依頼された場合
• ログだけでは失敗の原因を説明できず、トリアージでこのスキルが推奨された場合

プロパティ失敗に関する警告

ライブランで runs exec を使ってコマンドを実行すると、そのランのアサーションが発動し、実際のバグとまったく同じように見えるプロパティ失敗が発生することがあります。

この種の誤検知を避けたい場合は、デバッグセッションを使用してください。 この問題を引き起こさないと思われるコマンドについては、速度や使いやすさ、コア時間の節約を優先し、現在実行中のランを使用してください。

前提条件

• snouty がインストールされていない場合は、作業を進めないでください。インストール方法については https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md を参照してください。
• snouty が 0.8.0 より古い場合は、作業を進めないでください。0.8.0 は runs exec が安定した最初のリリースです。snouty --version でバージョンを確認してください。更新するには snouty update を実行してください。
• このコマンドを使うには、ライブランまたは MVD セッションのセッションが必要です。詳しくは、まずライブセッションを取得する方法を参照してください。
• snouty から Antithesis テナントにログインしている必要があります。snouty doctor を実行して確認してください。ログインしていない場合は、ユーザーにログインを依頼するか、API キーを使用してください。

まずライブセッションを取得する

• exec にはライブセッションが必要です。セッションはランまたは MVD セッションのどちらかに紐付けられます。snouty では、ランもデバッグセッションもランとして表示されます。

• ランの実行中と、終了後の短時間はセッションが保持されます。完了から数分後であれば動作しますが、数時間後には動作しません。

• ランにアクティブなセッションがあるか確認するには、次のコマンドを使います。

  snouty --json runs show <run> | jq -r '[.status, .sub_status // empty] | join(":") | ascii_downcase'
  

  これにより、ステータスとサブステータスがまとめて表示されます。in_progress:ready は、そのランに対してコマンドを実行できることを示します。in_progress:loading など、ほかのサブステータスを伴う in_progress は、セッションがまだ読み込み中であることを示します。 snouty runs wait <run> --until ready は、ランが使用可能になるか、すでに終了している時点で戻ります。停止時のステータスが表示されるため、exec を実行する前に in_progress:ready であることを確認してください。

• ユーザーからデバッグセッションの URL が提示された場合、そのセッションはすでに実行中の可能性があります。セッションのタイトル、説明、または作成日時を照合して、セッション一覧からラン ID を見つけてください。runs list にはステータスのみが表示されるため、in_progress のセッションを選び、runs show で in_progress:ready と報告されることを確認してください。

  snouty --json runs list --launcher debugging \
    | jq -c '{run_id, status, created_at, title: .parameters["antithesis.test_name"],
              source_run: .parameters["antithesis.debugging.run_id"]}'
  

  source_run の値を --source-run-id に渡します。

• 古いランの場合は、まずデバッグセッションを作成してください。

  snouty debug --run-id <run> --input-hash <hash> --vtime <vtime> \
    --title "Counter property failure 2026-10-13"
  

  • 後で見つけやすい一意の --title を必ず指定してください。たとえば、プロパティ名に日付またはチケット ID を加えます。これは snouty runs list にセッション名として表示されます。タイトルに収まらない理由がある場合に限り、--description を追加してください。--recipients には、通知先のメールアドレスをセミコロン区切りで指定します。
  • 新しいラン ID が返されます。snouty runs wait <new run ID> --until ready で待機してから、そのランに対して exec を実行してください。
  • 最初のコマンドには --source-run-id <run> を指定してください。時点がまだウォームアップされていないためです。ソースを指定すると、時点の準備ができるまで、再ウォームアップの進捗が N% と表示され、呼び出しはブロックされます。
  • snouty debug の実行から最初の exec の成功まで、2〜20 分かかることを想定してください。セッションの読み込み中は数分間 404 が発生し、その後、vtime が進んでいる時点ほど再ウォームアップに時間がかかります。ウォームアップが完了すれば、その時点に対する後続のコマンドではソースは不要です。
  • exec が 404 または「Moment not warm」を返す場合は、セッションがまだ読み込み中です。再試行してください。ユーザーのリクエストに適した input-hash と vtime を見つけるには、「時点を取得する」を参照してください。

瞬間を取得する（入力ハッシュと vtime）

input-hash と vtime で、デバッグする単一の瞬間を特定します。コンテキストから入力ハッシュと vtime を抽出して、コマンドに渡します。

ユーザーから瞬間が指定されていない場合は、references/moments.md を読み、見つけ方を確認します。

明確な情報源から入力ハッシュと vtime の両方を特定できない場合は、推測せずにユーザーに尋ねてください。

失敗または成功したプロパティ、あるいはログ行から瞬間（入力ハッシュ + vtime）を見つけるには、snouty runs search で検索します（ワークフロー例のステップ 3 を参照）。

必須の入力

• RUN_ID は、実行中の run、またはデバッグセッションの run id です。

• INPUT_HASH と VTIME は、その run の瞬間を示す値です。snouty runs search が返す 1 つのイベントから、ペアで取得します。

• INPUT_HASH は負の値であることがよくあります。たとえば -1520695250096255483 です。そのまま渡してください。snouty はこれをフラグではなくハッシュとして読み取るため、-- は不要です。-- を追加すると、それ以降のすべてのフラグが位置引数として扱われ、コマンドが正しく動作しなくなります。

  snouty runs exec "$RUN_ID" -1520695250096255483 67.7622960046865 'uptime'
  

• SCRIPT は実行する bash です。最後の引数として渡すか、省略して入力をパイプで渡します（例：< script.sh）。

オプションのフラグ

• --timeout DURATION は、サーバーがスクリプトの終了を待つ時間です。単位を指定します：90s、5m、1h。数値のみの場合は秒として扱われます。デフォルトは 10m です（リリース 64.0 時点）。休止状態の瞬間を再度起動する時間は、これに含まれません。
• --container NAME は、そのコンテナー内でスクリプトを実行します。指定しない場合、スクリプトはホスト上で実行されます。
• --source-run-id ID は、休止状態の瞬間が属する run を指定します。対象がデバッグセッションの場合、これはセッション id ではなく、セッションを開始した run です。デバッグセッションの開始後、最初のコマンドでこのフラグを使用してください。
• --source-session-id ID は --source-run-id に代わるセッション指定です。両方を同時に使用することはできません。
• --events は、スクリプトの出力だけでなく、スクリプトの実行中にタイムライン上のすべてのイベントをストリーミングします。
• --json は、機械可読な json 出力を表示します。

実行のヒント

• 1 つのコンテナーでコマンドを実行するには、スクリプト内で podman exec を使うよりも --container を使用してください。

• --container にはコンテナー名が必要で、Docker Compose テストでのみ機能します（下記の Kubernetes テストを参照）。すでに snouty runs search または snouty runs logs を実行している場合は、コンテナーログイベントの source.container から名前を取得してください。そうでない場合は、--container を指定せずに一度実行して、ホスト上で以下のコマンドを実行し、コンテナーを一覧表示します。

  snouty runs exec "$TARGET" "$HASH" "$VTIME" 'podman ps -a --format "{{.Names}} {{.Status}}"'
  

  Docker Compose テストでは、run 内のどの瞬間でもコンテナー名は同じなので、一度だけ一覧表示すれば十分です。

• --container は、その瞬間に実行中のコンテナーでのみ機能します。以前にクラッシュまたは終了している場合、podman ps -a では Exited と表示され、--container は失敗します。まだ起動していた以前の瞬間から実行してください。コンテナーの最後のログ行を snouty runs search で検索して、対象の瞬間を見つけます。

• 複数のコンテナーにまたがるスナップショットが必要な場合は、--container を使わず、ホスト上で実行してください。

• run からファイルを取り出すには、ファイルの内容を標準出力に出力し、ローカルにリダイレクトします。

  # text
  snouty runs exec "$TARGET" "$HASH" "$VTIME" --container app 'cat /var/log/app.log' > app.log
  
  # binary or a directory: tar + base64, then decode locally
  snouty runs exec "$TARGET" "$HASH" "$VTIME" --container app \
    'tar czf - /data/db | base64' | base64 -d > db.tgz
  

Kubernetes テスト

--container は Kubernetes テストでは機能しません（snouty runs show の launcher に「Kubernetes」または「k8s」が含まれています）。このフラグは指定せず、references/kubernetes.md を読んでください。

ファイルからスクリプトを実行する

• 1 行を超えるスクリプトは、ファイルに書き込んで入力をリダイレクトしてください。

  cat > script.sh <<'EOF'
  echo "host: $(hostname)"
  ps aux
  EOF
  
  snouty runs exec "$RUN_ID" "$INPUT_HASH" "$VTIME" < script.sh
  

  'EOF' を引用符で囲むと、誤って自分のマシン上で $(hostname) が実行されるのを防げます。

• 1 つのスクリプトを複数の瞬間で再利用します。同じファイルを複数の瞬間で実行し、出力を比較してください。

• 瞬間の名前を付けたファイルに出力を保存します。

• --events の出力は必ずファイルに保存してください。ストリームは長いため、あとでファイルを grep してください。

  snouty runs exec --events $RUN $HASH $VTIME < oracle.sh > out.txt
  grep -E "FAIL|HIT|exit" out.txt
  

タイムアウトとタイミングの選び方

• --timeout はスクリプトの実行時間だけを考慮して設定します。コールド状態のモーメントは先に再ウォームされます。これには数分かかることがあり、モーメントの vtime が後の時点ほど長くなりますが、この時間は --timeout に含まれません。遅いスクリプトの場合に限り、たとえば --timeout 30m のように延長してください。
• タイムアウトしても、スクリプトが実行されなかったとは限りません。状態を変更する処理を再実行する前に、実行結果を検索してください（snouty runs search）。
• スクリプトを実行すると仮想時間が進みます。スナップショットは短く保ってください。ポーリングすると観察しようとしているタイミングが変わることがあるため、ポーリングするのではなく、適切なタイミングで一度だけクエリを実行してください。
• 同じモーメントで同じコマンドを実行すると、同じ分岐が得られます。繰り返しても新しいタイミングはサンプリングされません。
• ソースを指定した exec が一度成功すると、そのモーメントはセッション内でウォーム状態になります。その後のコマンドではソースを指定する必要はなく、すぐに結果が返ります。
• セッション独自のタイムライン上にある、より前のモーメントもウォーム状態なので、再ウォームは不要です。

再ウォームの進捗

コールド状態のモーメントを再ウォームしている間は、進捗が表示されます。デフォルトでは、コマンドは標準エラーに rewarming moment: N% の行を出力します。--json を指定すると、スクリプトの出力より前に、標準出力へ {"status":"rewarming","percent_complete":N} のフレームが出力されます。

• パーセンテージが上昇している場合、再ウォームは進行中です。上昇している間は、再試行したりキャンセルしたりしないでください。
• 数分間 0% のままになった後、ほぼ 100% まで一気に上昇することがあります。0% で停滞していても、失敗ではありません。呼び出しを実行したままにしてください。

完了したらキャンセルする

実行とデバッグセッションは、終了するまでコア時間を消費します。デバッグセッションは、使用をやめても終了しません。デフォルトでは、6 時間後にのみ期限切れになります。開いたセッションが不要になったとき、または当面必要なくなったときは、すぐにキャンセルしてください。

snouty runs cancel "$TARGET"

• セッションをキャンセルする前に、ユーザーに確認してください。作業が終わった後も、別のデバッグセッションで引き続き使用したい場合があります。
• 実行やデバッグセッションをキャンセルする前に、完全に作業が完了していることを確認してください。追加のコマンドを実行したくなった場合、新しいセッションのセットアップを待つ必要があります。
• ユーザーから依頼されない限り、自分が開いていない実行はキャンセルしないでください。

ワークフローの例

1. 前提条件

snouty --version   # 0.8.0 or newer

2. セッションを取得する

RUN=<run_id>
snouty --json runs show "$RUN" | jq -r '[.status, .sub_status // empty] | join(":") | ascii_downcase'

• in_progress:ready：実行自体を使用します。TARGET="$RUN" とします。

• starting、または別のサブステータスを伴う in_progress：snouty runs wait "$RUN" --until ready で待機し、出力されたステータスが in_progress:ready の場合は、その実行を使用します。

• それ以外の場合：モーメントを選択し（手順 3）、その時点でセッションを開いて、準備が整うまで待ちます。読み込み中に 404 または「Moment not warm」が発生した場合は、exec を再試行してください。

  snouty debug --run-id "$RUN" --input-hash "$HASH" --vtime "$VTIME" --title "<property> <date>"
  TARGET=<runId from the output>
  snouty runs wait "$TARGET" --until ready
  

3. モーメントを選択する

snouty runs search でモーメントを検索し、調べたいイベントだけを正確に指定してクエリを実行します。たとえば、あるプロパティの評価失敗を検索する場合：

snouty --json runs search "$RUN" \
  'filter(ev => ev.antithesis_assert?.hit
    && ev.antithesis_assert.id == "<property name>"
    && !ev.antithesis_assert.condition)' \
  | jq -r '.moment | "\(.input_hash) \(.vtime)"'

評価が成功したものを検索するには、! を削除してください。ログ行を検索するには、contains({output_text: "<error text>"}) を使用します。メッセージでアサーションを検索するには、filter(ev => ev.antithesis_assert?.message?.includes("<message text>")) を使用します。アサーションには output_text がないため、ログ行のクエリでは見つかりません。references/moments.md を参照してください。

デフォルトでは、runs search は最大 50 件の結果を返します。数件より多く必要な場合は、--limit 999 を追加してください。

4. Exec

セッションの開始後に実行する最初のコマンドでは、モーメントがまだウォームアップ中のため、--source-run-id を使用します。その後はモーメントがウォーム状態になるので、モーメントを変更しない限り、後続のコマンドでソースを指定する必要はありません。

cat > probe.sh <<'EOF'
hostname
ps aux | head -20
EOF

snouty runs exec "$TARGET" "$HASH" "$VTIME" --source-run-id "$RUN" < probe.sh > out.txt

5. 結果を使用する

通常はバグの原因を特定するなど、ユーザーの目的に合わせて出力を活用します。出力で質問に答えられない場合は、より前のモーメントで再度 exec を実行するか、end moment の行から続行してください。

必要に応じて、ユーザーが再実行できるように、モーメント、スクリプト、関連する出力を伝えてください。

6. キャンセル

セッションを開いた場合は、コマンドの実行が終わった後で、実行をキャンセルするかユーザーに確認してください。キャンセルしない場合、6 時間後に期限切れになるまでコア時間を消費し続けます。

snouty runs cancel "$TARGET"

gdb

gdb でプロセスを調査するには、references/gdb.md を読んでください。

仮想時間

時点を選ぶ前、または一時的なイベントを調べる前に、 references/virtual-time.md を読んでください。

以前の時点がウォーム状態でない場合は、--source-run-id を追加してください。

よくあるエラー

exec がエラーを返した場合は、references/errors.md を読んでください。

セルフレビュー

報告する前に、次の基準に照らして作業を確認してください。

• すべての調査結果は、推測や仮定ではなく、実際の exec の出力に基づいています。
• 証拠の流れが明確です。時点（入力ハッシュと vtime）、スクリプト、その返却内容、そこから導かれることが示されています。
• 要約では、出力が示していることと、解釈または推奨事項を分けています。
• 開始したデバッグセッションをキャンセルするかユーザーに確認したか、またはセッションがまだ実行中であることをユーザーが把握しています。

既知の問題

• snouty runs wait --until ready が返った後も、exec が数分間 404 を返すことがあります。セッションはまだ読み込み中なので、再試行を続けてください。
• snouty runs cancel の後、実行のステータスが cancelled ではなく completed と表示されることがあります。キャンセルは成功しています。