meteor-debugging

Meteor アプリケーションのデバッグ

動作を変更する前に、最初に失敗する境界を見つけてください。安定して再現できる方法、原因を裏付ける証拠、検証対象を用意します。その後、修正を担当するスキルを使用してください。

診断ループ

1. 正確な症状、エラーとスタックの全体、コマンドまたはユーザー操作、Meteor のリリース、解決された Atmosphere と npm のバージョン、環境、最後に正常に動作していた状態を記録します。
2. 編集する前に、最も範囲を絞った安定したコマンドまたは操作で再現します。
3. 以下の表を使って、最初に不確かな境界を分類します。
4. 計測を追加する前に、既存の証拠を確認します。クライアントとサーバーの出力、最近の変更、成功している環境と失敗している環境を比較します。
5. 現在の証拠では疑問に答えられない場合に限り、対象を絞った観察を一つ追加します。診断のための変更と推測に基づく修正を組み合わせないでください。
6. 反証可能な仮説を一つ述べ、それを否定する観察内容を示します。
7. 変数を一つ変更して再現し、不正な値やイベントを発生源まで遡って追跡します。
8. 確認した原因を担当するスキルで修正します。障害が再発し得る場合は、信頼性の高い最も低いレイヤーに回帰テストを追加します。
9. 対象を絞った再現を再実行し、その後、影響を受けるテストスイートまたは本番相当のチェックを実行します。一時的な診断コードと生成物を削除します。

証拠に裏付けられた仮説が複数失敗した場合、緩和策を重ねたり変更範囲を広げたりする前に、境界マップと前提を見直してください。

境界を選択する

症状	最初に確認する証拠	参照先
ビルドの停止、コンパイルエラー、再ビルドのリグレッション、Rspack または SWC の失敗	ビルド出力全体、--verbose、正確なリリースとビルドパッケージのバージョン	ビルドのデバッグ
サーバーが起動前にクラッシュする、またはメソッド、パブリケーション、ジョブ、フックで失敗する	サーバースタックの最初の箇所、起動順序、リクエストと関連付けられた証拠	ランタイムとインスペクター
クライアントのスタック、古いレンダリング、リアクティブループ、またはクライアントとサーバーの不一致	ブラウザのスタック、レンダリングされた状態、リアクティブな無効化、サーバーとの比較	ランタイムとインスペクター、続いて React または Blaze のスキル
ドキュメントの欠落、サブスクリプションの停滞、再接続、またはプロキシ／WebSocket の症状	サーバークエリ、パブリケーションの出力、DDP の状態、サブスクリプションの準備状況、Minimongo	DDP とデータ
現在の出力では、エントリー、ガード、分岐、状態変更、イベント順序を判別できない	マスキングした境界観察の小さなセット	ログと計測
Meteor Mocha の失敗、テストスイート限定の失敗、非同期処理の不安定な失敗、またはブラウザ E2E の失敗	フック出力全体、クライアント／サーバーのテスト数、既存のレポートとトレース	テストとブラウザ
Cordova または HCP の問題、デバイス限定の失敗、または本番環境のインシデント	デバイスのログとバージョン、デプロイログ、ヘルス、メトリクス、リリース差分	モバイルと本番環境

構文エラーにはスタックが必要であり、ブラウザーのトレースではありません。ブラウザー限定のハイドレーション競合にはクライアントの証拠が必要であり、サーバーインスペクターではありません。現在の仮説を否定できる最小限のツールを使ってください。

エビデンスのルール

• 一時ログには実行側と操作を記録します。同時に実行されるフローが混在する可能性がある場合に限り、リクエストまたはイベントの識別子を含めます。
• 選択したフィールドを記録し、機密情報を除去します。認証情報、トークン、Cookie、認可ヘッダー、非公開設定、制限のないメソッド引数、ユーザーのドキュメント全体は決してログに記録しないでください。
• console.log は一時的な計測手段として扱います。永続化が必要なエビデンスには、meteor/logging またはアプリケーションで既に採用されている構造化ロガーを使用します。
• Meteor 3.6-beta.1 から beta.3 におけるサーバーのライフサイクルを示すエビデンスには、ログと計測を通じてオプションの instrumentation パッケージを使用します。それ以前のリリースでは、対象を絞ったログを引き続き使用します。リスナーは状態を監視するものであり、認可するものではありません。
• .only は、テストランナーと実行モードが対応している場合に限り、一時的なローカルでのテスト対象の絞り込みに使用します。引き継ぎ前に削除し、より広い範囲のテストスイートを実行してください。
• スリープより、観測可能な準備完了状態を優先します。たとえば、サブスクリプションの準備完了、メソッドの処理完了、期待するドキュメント、表示された UI、特定のブラウザーイベントなどです。
• インタラクティブなブラウザーを起動する前に、既存の Playwright レポートとトレースを確認します。playwright-cli の使用を求められた場合は、まず実行ファイルが利用可能か確認します。利用できない場合、インストールまたはブラウザーのダウンロードを行う前に許可を得てください。利用可否の確認結果を明示して、アプリケーションの URL だけを尋ねるのではなく、許可を求めます。実際のブラウザー境界でのみ使用してください。
• 許可を得て playwright-cli で臨時に再現する場合は、snapshot、console、requests を必ず実行し、失敗する操作の前にトレースを開始し、その操作の直後にトレースを停止して、ブラウザーセッションを閉じてください。ブラウザーのエビデンスの代わりにソースコードを調査したり、コンソールやネットワークから原因が示唆されていることを理由にトレースを省略したりしないでください。
• ユーザーが対象範囲に含めたアプリケーションのパスまたは URL のみを使用します。現在のワークスペースにアプリケーションがなく、プロンプトにも URL が記載されていない場合は、URL を尋ねてください。アプリケーションを探すために、無関係なディレクトリ、プロセス、ポートを調べないでください。
• 変更を加える前に、meteor shell と meteor mongo を通じて内容を読み取ってください。診断の手っ取り早い手段として meteor reset --db を決して使用しないでください。
• 本番環境では、インスペクターを公開したり、デバッグビルドをデプロイしたり、秘密情報を含むトレースを保管したり、稼働中のデータを使って実験したりしないでください。

引き継ぎ

確認済みの原因	引き継ぎ先
テストのセットアップ、設計、ドライバー、フィクスチャ、または新しいリグレッションテストの構成	meteor-testing
SWC、Rspack、ウォッチャー、キャッシュ、ビルドグラフ、または生成後の引き継ぎ	meteor-modern-build-stack または migrate-to-rspack
Cordova のプラットフォーム、ネイティブプラグイン／設定、デバイスネットワーク、署名、またはネイティブ HCP との互換性に関する確認済みの問題	meteor-native
メソッド、パブリケーション、Mongo／Minimongo、React、Blaze、アカウント、またはセキュリティ	対応するドメインスキル
Galaxy、コンテナ、プロキシ、環境、ヘルスチェック、またはロールアウト	meteor-deployment
ドキュメント化されたコミュニティパッケージの動作	meteor-community-packages、続いてアップストリームのリポジトリ
Meteor の境界に関係しない、純粋な Node.js、ブラウザー、データベース、またはテストランナーの障害	一般的なデバッグガイダンス

クリーンアップ

引き継ぎの前に、次の作業を行います。

1. 今回の調査で追加したログ、debugger 文、.only マーカー、一時停止、一時ルート、デバッグ設定のみを削除します。
2. スクリーンショット、トレース、プロファイル、保存したブラウザー状態、ダンプは、データの機密性に応じて削除または保護します。
3. 元の再現手順を実行し直し、影響を受けたテストスイートを再実行します。
4. 確認済みの原因、エビデンス、修正、検証結果、および残っている不確実性を報告します。

アンチパターン

• セットアップ、非同期処理の完了、クライアントのテスト対象範囲を確認する前に、アサーションを編集します。
• 仮説を立てずに、アプリケーション全体にログを追加します。
• すべてのランタイムオブジェクトを無差別にシリアライズします。循環参照を含む値、リアクティブなラッパー、ゲッター、バイナリデータ、大きなドキュメントには、対象を絞ったスナップショットが必要です。
• スイート全体で失敗が続いているのに、特定のテストが通っただけで成功と見なします。
• 症状が消えるまで、根拠のない待機時間、広範なセレクター、再試行、ヒープサイズの増加を追加します。
• サーバー、ビルド、データベースの問題に対処するために、ブラウザツールをインストールしたり、テストを足場から構築したりします。

参考資料

• ランタイムとインスペクター
• ログと計装
• テストとブラウザー
• ビルドのデバッグ
• DDP とデータ
• モバイルと本番環境
• 評価ケース