Heartbeat・Breadcrumb・Shadow Mode：エージェントの運用状態を読み解く用語
約12分developer-tools
#ハートビート#ブレッドクラム#シャドウモード#パイプ#リダイレクト#AIコーディングツール#用語集
※ 編集方針：以下の業務状況および人物は、用語の理解を助けるための架空のシナリオです。実際の著者の経験や特定企業の出来事を再現したものではありません。
障害対応の夜番の最中、深夜に決済サーバーの応答停止アラートを受信した、架空の運用状況を想定してみましょう。
ダッシュボードを開いてみると、アラートが発生する5分前から、すでに異常なシグナルが出ていたことに気づきました。
サーバーが停止する前からすでにシグナルがあったとき：ハートビート
text
102:11:00 heartbeat OK202:11:30 heartbeat OK302:12:00 heartbeat missed402:12:30 heartbeat missed → alert fired
同僚が以前作成した監視設定を開いてみると、30秒ごとにサーバーへ「生きてる？」と生存を確認するシグナルを送信するようになっていました。
一定の間隔で信号を送受信し続け、応答が途絶えた瞬間を即座に検知する仕組みでした。人の脈拍を測るように、一定のリズムが途切れた瞬間がすなわち異常の兆候です。アラートが鳴った時点よりも前に、事例の中の担当者はすでに障害が発生し始めたポイントを特定できていました。
原因の起点は分かりましたが、具体的にどのリクエストによってサーバーが停止したのかは、依然として霧の中でした。
一つのエラーの原因を遡るとき：ブレッドクラムが残した足跡
ログシステムが自動的に残していた痕跡を辿っていくと、各リクエストが経由した経路が順序通りに残っていました。
text
1[req-9f21] api-gateway → payment-service → db-pool(대기 중)
一つのリクエストが複数のサービスを経由する間、通過した経路を順序通りに残すことで、事例の中の担当者がどこで処理が詰まったのかを逆算して辿れるようにする痕跡です。童話の中の子供たちが森にパンくずを落として帰り道を印したというアイデアと同じ発想なので、名前の意味を知るとかえってイメージしやすくなります。この痕跡のおかげで、db-poolで待機が発生していることをすぐに突き止めることができました。
db-poolの設定を修正しようとデプロイ履歴を探っていたところ、数ヶ月前に事例の中の担当者が自ら適用した設定を再び見つけました。
新バージョンを実際にアクティブにすることなく事前に検証するとき：シャドウモード
yaml
1mode: shadow2new_pool: enabled3serve_traffic: false
数ヶ月前、DBの接続方式を新しく変更する際に不安があり、このように設定していたことをすっかり忘れていました。新バージョンが実際のユーザーに対しては応答しない一方で、同じリクエストをバックグラウンドで密かに処理し、結果だけを比較する方式でした。影が実体に寄り添うように、実際のサービスの後ろに隠れて同じ処理をこっそり行っていました。今回の障害は、このシャドウバージョンが検知できなかった例外的な状況によるものでした。
DBの待機問題を解決してログを整理していたところ、チームチャットに残っていた同僚の古いコマンドが、どうしても気になりました。
コマンドの後ろにつく見慣れない記号の意味が分からないとき：パイプ
bash
1$ cat error.log | grep "db-pool" | wc -l
この記号を見るたびに何をするものなのか分からず、コマンドを一つずつ個別に実行しては、結果を手動でコピーして貼り付けていました。同じような面倒な作業を何度も繰り返した末に、ようやくこの記号の役割をちゃんと調べてみました。
あるコマンドの出力結果を、そのまま次のコマンドの入力として渡す連結用の仕組みでした。縦棒（|）の形状がまるで水が流れる管のように見えることから「パイプ」という名前がついていますが、名前の由来よりも、実際に手動でコピーしていた作業を1行に省略できるという事実のほうが、はるかに身に染みて感じられました。
パイプで絞り込んだ結果をチームに共有するためにファイル保存しようとしたところ、今度はまた別の記号が壁となりました。
結果を画面ではなくファイルに出力したいとき：リダイレクト
bash
1$ cat error.log | grep "db-pool" > incident-report.txt
検索してみると、
> 記号の役割はパイプと似ているようで異なっていました。 本来画面に出力されるはずの結果を、画面の代わりに指定したファイルへと出力の向きを変えて保存することでした。蛇口から流れる水をそのままシンクに流す代わりに、ホースを繋いで別のバケツに貯めるようなものです。深夜4時近くになってようやく、障害報告書のドラフトをこの方法で保存し、デスクから立ち上がることができました。
決済サーバーは深夜4時頃に正常な状態に戻りました。アラートが鳴ったのは2時でしたが、シグナルはそれよりずっと前から画面のどこかに残っていました。 夜番業務の半分は問題を解決することであり、残りの半分はすでに残されていた記録を読み解くことでした。
よくある質問
ハートビートの間隔は短いほど良いのでしょうか？
間隔が短いほど問題をより早く検知できますが、その分サーバー間でやり取りする信号そのものが負荷になります。サービスの重要度に応じて、数秒から数十秒の間で妥協点を見つけるケースが多いです。
シャドウモードで検証すれば、実際の障害を完全に防ぐことができますか？
完全には防げません。シャドウモードは普段のトラフィックパターンで問題がないかを検証してくれるだけで、今回のように稀に発生する例外的な状況まですべてをカバーできるわけではありません。
パイプとリダイレクトを一緒に使ってもいいですか？
はい、実際に併用されることが多いです。複数のコマンドをパイプで繋いで結果を絞り込んだ後、最後にリダイレクトでファイルに保存するという組み合わせが一般的です。
AIコーディングツール用語集シリーズの第7回です。次回予告 · 第8回：一つのサービスが停止し、隣にあったものまで連鎖的に倒れていった夜 | サーキットブレーカー・デッドレターキュー・シンボリックリンク・デーモン・ソケット
参考・根拠
関連記事
サブエージェント・フック・スラッシュコマンド：AIコーディングツールでよく使われる拡張概念
AIコーディングツールの使用中に出会う「サブエージェント」「フック」「スラッシュコマンド」を、架空の業務シナリオを交えて分かりやすく解説します。
パーミッションプロンプト・Sandbox・Checkpoint：AIエージェントの実行境界を理解する
AIコーディングツールを使う中で直面するパーミッションプロンプト、サンドボックス、チェックポイントなど5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。
Kill Switch・Backoff・Runtime：実行を停止し復旧するための基本機能
AIコーディングツールを使っていると遭遇する、キルスイッチ、バックオフ、リポジトリなどの5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。