connectivity-triage

接続性トリアージ

ネットワーク設定を変更せずに、発生中の接続障害を切り分けます。必要最小限の有用な証拠を収集し、観測と推測を区別し、次の安全なアクションに進める程度に障害ドメインが明確になった時点で停止します。

このスキルを使用する場面

macOS エンドポイントで次のような症状が発生している場合に、このワークフローを使用します。

• API、Web サイト、または MCP サービスがタイムアウトする、または切断される。
• DNS ルックアップの失敗、または名前解決の一貫性の欠如。
• パケットロス、レイテンシ、または対話型トラフィックの不安定さ。
• 他のトラフィックは機能しているのに、特定のアプリケーションがオフラインに見える。
• 問題がローカル、上流、またはサービス側のどこにあるか不明である。

これは診断ワークフローであり、修復ワークフローではありません。障害ドメインを特定している間は、インターフェイスの状態、DNS 設定、VPN/ファイアウォール設定、またはリモートサービスの状態を変更しないでください。

迅速な判断フロー

症状から出発し、最も狭く切り分けられるチェックへと進みます。

symptom
  -> local link / LAN evidence
  -> DNS configuration and resolution
  -> destination reachability
  -> path quality
  -> application / service timing
  -> fault-domain assessment

証拠がすでに十分であれば、早い段階で停止してください。すべてのプローブを機械的に実行しないでください。

1. 症状を定義する

影響を受けているアプリケーションまたはプロセス、宛先のホスト名または URL、障害の発生時期、継続的か断続的か、および無関係な宛先がまだ機能しているかどうかを記録します。

症状がアプリケーション固有の場合は、そのアプリケーションが使用している正確なホスト名または URL を保持してください。無関係なパブリックサイトをテストしても、一般的な接続性は確認できますが、影響を受けているサービスが正常であることを証明することはできません。

2. ローカルリンク / LAN の証拠を確認する

利用可能な場合は、全体的な応答性とスループットのシグナルとして、時間を区切った networkQuality サンプルを実行します。networkQuality が利用できない場合は、そのまま続行してください。これは省略可能です。

既知のローカルゲートウェイまたは同一 LAN 上のターゲットが利用可能な場合は、そのローカルターゲットへの短い時間制限付き ping サンプルと、リモート宛先への短いサンプルを比較します。ゲートウェイアドレスをでっち上げないでください。既知のローカルターゲットがない場合は、LAN セグメントは未検証のままにして続行してください。

有用なパターン:

ping -c 5 <known-local-target>
ping -c 5 <destination>

3. DNS 設定と DNS の動作を分離する

特に VPN、スプリット DNS、またはスコープ付きリゾルバーが関与している可能性がある場合は、システムリゾルバーの状態を確認します。

scutil --dns

次に、時間制限付きの DNS クエリで宛先名を直接テストします。

dig +time=2 +tries=1 <hostname>

これらは異なる証拠として扱ってください。scutil --dns はリゾルバー設定を示し、dig はクエリの動作を示します。ルックアップの成功は、返されたエンドポイントに到達可能であることを証明するものではありません。

4. 到達可能性とパス品質をテストする

ICMP が有用なシグナルとなる場合は、短い ping サンプルを使用します。

ping -c 5 <destination>

ホスト名が解決される場合は、DNS の動作とパスの障害を区別するのに役立つ場合に限り、返されたアドレスを別途テストしてください。解決が現在失敗している場合は、信頼できるインシデント証拠から以前に観測されたアドレスである場合にのみアドレスを使用し、それ以外の場合はアドレスレベルの到達可能性を不明のままにしてください。

パスの可視性が不確実性を減らす場合は、時間制限付きの数値 traceroute を使用します。

traceroute -n -q 1 -m 20 <destination>

応答がないホップや変化するホップは観測であり、そのホップが壊れていることの証明ではありません。ルーターはアプリケーショントラフィックを正常に転送しながら、traceroute トラフィックをフィルタリングまたはレート制限する場合があります。

5. 影響を受けているアプリケーションのライブネットワークアクティビティを確認する

問題がプロセス固有の場合は、無期限に監視するのではなく、時間制限付きの nettop キャプチャを使用します。

nettop -n -L 3 -p <process-name-or-pid>

これを使用して、プロセスが接続を開いているか、どのエンドポイントを使用しているか、トラフィックが流れているかを確認します。アクティビティが見えないことは、アプリケーションが接続を試みなかったことを意味する場合がありますが、それ自体でその理由を特定するものではありません。

6. アプリケーションパスの時間を計測する

HTTP(S) の場合、安全な読み取り専用リクエストが利用できるときは、実際に影響を受けているエンドポイントに対して curl のフェーズタイミングを使用してください。インシデントで提供されたエンドポイントが完全な http:// または https:// の URL であることを確認し、元のスキームを保持し、任意のインシデントテキストをシェルコマンドに補間するのではなく、URL を引用符で囲んだ 1 つの引数として渡してください:

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  --connect-timeout 5 --max-time 15 '<affected-http-or-https-url>'

各フェーズを比較して解釈してください。time-to-first-byte が大きい場合はサーバー側の処理が含まれる可能性があるため、ネットワーク遅延の証拠にはなりません。

証拠のルール

結論を次のいずれかとしてラベル付けしてください:

• Observed (観測) — コマンド出力またはユーザー提供の証拠によって直接裏付けられている。
• Inferred (推論) — 観測事項を関連付けた後で最も可能性が高い説明。
• Unknown (不明) — 現在の証拠では立証されていない。

1 回のプローブを根本原因の証拠として扱わないでください。特に:

• ping の失敗は、障害ではなく ICMP フィルタリングを反映している可能性があります;
• ping の成功は、アプリケーションが正常であることを証明しません;
• traceroute のホップが応答しないことは、それらの中間ルーターでのパケット損失を証明しません;
• DNS 解決の成功は、到達可能性を証明しません;
• HTTP の first-byte time が大きい場合は、リモートアプリケーションの処理が支配的である可能性があります。

観測事項が矛盾する場合は、自信のある推測よりも inconclusive を優先してください。

障害ドメインの評価

主カテゴリを 1 つだけ返してください:

• local-link/LAN — ローカルネットワーク境界の手前または境界で証拠が悪化している;
• DNS — リゾルバーの設定またはルックアップの挙動が、パスの証拠よりもよく障害を説明する;
• upstream-path — ローカルの証拠は健全であり、関連付けられたパスの証拠が LAN の先で悪化している;
• remote-service/application — トランスポート/パスの証拠は十分に健全である一方、影響を受けているサービスまたはプロセスの挙動が異常なままである;
• inconclusive — 現在の証拠では残りの障害ドメインを切り分けられない。

定性的な信頼度を使用してください: low、medium、または high。信頼度は証拠の品質と相関関係を反映するものであり、深刻度を反映するものではありません。

インシデント結果のフォーマット

症状

現在発生している障害と、影響を受けている宛先/アプリケーションを言い換えてください。

観測事項

関連する測定値のみを列挙し、重要でありながら利用できない、またはブロックされた証拠も含めてください。観測、推論、不明を明確にマークしてください。

障害ドメインの評価

カテゴリ、信頼度、および証拠に関連付けた短い説明を報告してください。

次に最も安全な確認

不確実性を最も低減する診断アクションを 1 つ提示してください。ユーザーが別途修復を求めない限り、設定変更に飛びつかないでください。

安全性と境界

診断中は、次を行わないでください:

• インターフェースの状態を変更したり、ネットワークサービスを再起動したりする;
• リゾルバーの設定を編集したり、DNS キャッシュをフラッシュしたりする;
• ファイアウォールまたは VPN の設定を変更する;
• パッケージをインストールしたり、Homebrew を要求したりする;
• リモートサービスに状態を変更するリクエストを送信する;
• 限定されたサンプルで問いに答えられる場合に、無期限または大量のプローブを実行する。

部分的なプローブ、ブロックされた ICMP、VPN、キャプティブポータル、スコープ付き DNS、プロキシ、エンドポイント制御、および一時的な障害は、診断ではなく証拠の制約です。

詳細な解釈

コマンドごとの解釈、曖昧さの扱い、断続的な障害に関するガイダンス、および実例については references/details.md をお読みください。

関連スキル

• incident-runbook-templates - 繰り返し発生する接続インシデントを再現可能な対応手順に変える
• on-call-handoff-patterns - 対応者の引き継ぎを通じてアクティブな接続の証拠を保持する
• postmortem-writing - インシデント後に確認された原因と是正措置を文書化する