convex-performance-audit

Convex のパフォーマンス監査

Convex アプリケーションのパフォーマンス問題を、問題の種類ごとに診断して修正します。

使用するタイミング

• Convex のページや機能の動作が遅い、またはコストが高いと感じる場合
• npx convex insights --details で、読み取りバイト数、読み取りドキュメント数、または OCC の競合が多いと報告される場合
• 鮮度が低くてもよい読み取りパスで、ポイントインタイム読み取りで十分なのにリアクティビティを使用している場合
• OCC の競合エラーや、ミューテーションの過剰なリトライが発生している場合
• サブスクリプション数が多い、または UI の更新が遅い場合
• 関数が実行またはトランザクションの上限に近づいている場合
• 同じパフォーマンスパターンを、関連する関数全体で修正する必要がある場合

使用しないタイミング

• Convex の初期設定、認証の設定、またはコンポーネントの切り出し
• パフォーマンス目標のない純粋なスキーマ移行
• ユーザーやデプロイに影響する問題のない、一度限りのマイクロ最適化

ガードレール

• 規模が小さい、トラフィックが少ない、または利用可能なシグナルが弱い場合は、よりシンプルなコードを優先します
• 測定されたシグナル、明らかに上限のないパス、または既知のホットな読み取り／書き込みパスがない限り、ダイジェストテーブル、ドキュメントの分割、フェッチ戦略の変更、または移行を多く伴うロールアウトを推奨しないでください
• Convex では、小さなテーブルの単純なスキャンで十分なことがよくあります。大規模な場合に理想的でないというだけで、構造的な変更を持ち込まないでください

最初の手順：シグナルを収集する

利用可能な中で最も強いシグナルから始めます。

1. デプロイの Health insights がユーザーまたは現在のコンテキストからすでに利用できる場合は、パフォーマンスシグナルの主要な情報源として扱います。
2. CLI の insights が利用できる場合は、npx convex insights --details を実行します。必要に応じて --prod、--preview-name、または --deployment-name を使用します。
   • ローカルリポジトリの Convex CLI が古く、insights をサポートしていない場合は、諦める前に npx -y convex@latest insights --details を試してください。
3. リポジトリですでに convex-doctor を使用している場合、その検出結果をヒントとして扱ってもかまいません。使用を必須にせず、真実を示す情報源として扱わないでください。
4. ランタイムのシグナルを利用できない場合も、ガードレールを念頭に置きながらコードを監査してください。insights がないことは健全性の証明ではありませんが、大規模なリファクタリングが必要である証明でもありません。

シグナルに応じた対応

シグナルを収集したら、問題の種類を特定し、該当するリファレンスファイルを読みます。

シグナル	リファレンス
読み取りバイト数やドキュメント数が多い、JavaScript によるフィルタリング、不要な結合	references/hot-path-rules.md
OCC の競合エラー、書き込み競合、ミューテーションのリトライ	references/occ-conflicts.md
サブスクリプション数が多い、UI の更新が遅い、再レンダリングが過剰	references/subscription-cost.md
関数のタイムアウト、トランザクションサイズのエラー、大きなペイロード	references/function-budget.md
具体的なシグナルがない一般的な「動作が遅い」という問題	references/hot-path-rules.md から始めます

複数の問題の種類が重なる場合があります。最も関連性の高いリファレンスを先に読み、症状が残る場合はほかのリファレンスも確認してください。

大規模な修正にエスカレーションする

想定される修正が侵襲的、複数箇所にまたがる、または移行を多く伴う場合は、編集を始めず、まず選択肢を提示してください。

例：

• 複数のフローにまたがるダイジェストテーブルやサマリーテーブルの導入
• 頻繁に更新されるフィールドを分離するためのドキュメントの分割
• 複数の画面にまたがるページネーションやフェッチ戦略の再設計
• 移行に安全なロールアウトが必要となる、新しいインデックスや非正規化フィールドへの切り替え

ロールアウト中に新旧両方の状態を扱うことが正しさの要件となる場合は、移行ワークフローについて convex-migration-helper スキルを参照してください。

ワークフロー

1. 問題の範囲を絞る

実際のプロジェクトから、具体的なユーザーフローを1つ選びます。症状に該当するフローを見つけるため、コードベース、クライアントページ、API の範囲を確認します。

次の項目を書き出します。

• エントリーポイント関数
• useQuery、usePaginatedQuery、または useMutation を使用するクライアントの呼び出し箇所
• 読み取るテーブル
• 書き込むテーブル
• その処理経路が読み取り頻度の高いものか、書き込み頻度の高いものか、あるいは両方か

2. 読み取りと書き込みの全範囲を追跡する

処理経路に含まれる各関数について、次の項目を確認します。

1. すべての ctx.db.get() と ctx.db.query() を追跡する
2. すべての ctx.db.patch()、ctx.db.replace()、ctx.db.insert() を追跡する
3. 外部キーの検索、JavaScript 側でのフィルタリング、ドキュメント全体の読み取りを記録する
4. 同じテーブルを操作するすべての関連関数を特定する
5. 同じページに表示されるリアクティブな統計情報、集計データ、ウィジェットを特定する

Convex では、読み取りが1つ増えるごとにトランザクションの処理量が増え、書き込みが1つ発生するごとにリアクティブなサブスクライバーが無効化される可能性があります。読み取り増幅と無効化増幅を、第一級の問題として扱ってください。

3. 該当するリファレンスの修正を適用する

問題の種類に対応するリファレンスファイルを読みます。各リファレンスには、具体的なパターン、コード例、推奨される修正順序が記載されています。

インサイトで名前が挙がった関数だけを確認して終わりにしないでください。同じテーブルを操作する関連する読み取り関数と書き込み関数も追跡します。

4. 関連関数もまとめて修正する

あるテーブルを操作する関数にパフォーマンス上の問題が見つかった場合は、同じパターンがないか、関連関数も監査します。

問題を1つ見つけたら、関連するダイジェストテーブルやサマリーテーブルも含め、同じテーブル群を操作する関連する読み取り関数と書き込み関数の両方を確認します。

例：

• ある一覧クエリでドキュメント全体の読み取りからダイジェストテーブルの読み取りに切り替える場合は、そのテーブルを使用する他の一覧クエリも確認する
• あるミューテーションで頻繁に更新されるフィールドを分離するか、ホットドキュメントを分割する場合は、同じテーブルへの他の書き込み処理も確認する
• ある読み取り処理で、バックフィルされていないフィールドに対する移行対応のロールアウトが必要な場合は、関連する読み取り処理にも同じリスクがないか確認する

明確なプロダクト上の理由がない限り、ある処理経路だけを修正し、別の処理経路を古いパターンのままにしないでください。

5. 完了前に検証する

次の項目がすべて満たされていることを確認します。

1. 以前と同じ結果が得られ、レコードが失われていない
2. 削減した読み取りや書き込みが、想定どおり処理経路からなくなっている
3. 非正規化フィールドやインデックスフィールドが欠落している場合も、フォールバック動作が機能する
4. 必要な箇所では、頻繁に更新されるフィールドが広く読み取られるドキュメントから分離されている
5. 元の関数だけでなく、関連する読み取り関数と書き込み関数もすべて確認されている

リファレンスファイル

• references/hot-path-rules.md - 読み取り増幅、無効化、非正規化、インデックス、ダイジェストテーブル
• references/occ-conflicts.md - 書き込み競合、OCC の解決、ホットドキュメントの分割
• references/subscription-cost.md - リアクティブクエリのコスト、サブスクリプションの粒度、時点指定の読み取り
• references/function-budget.md - 実行制限、トランザクションサイズ、大きなドキュメント、ペイロードサイズ

監査中に見つかる可能性のある引数の検証、アクセス制御、コード構成に関する追加のパターンについては、公式の Convex Best Practices ページも確認してください。

チェックリスト

• インサイト、ダッシュボード、またはコード監査から手がかりを集めた
• 問題の種類を特定し、該当するリファレンスを読んだ
• 具体的なユーザーフローまたは関数の処理経路を1つ特定した
• その処理経路におけるすべての読み取りと書き込みを追跡した
• 同じテーブルを操作する関連関数を特定した
• 推奨される修正順序に従い、リファレンスの修正を適用した
• 関連関数にも一貫性を保って修正を適用した
• 動作を検証し、リグレッションがないことを確認した