debugging-apex-logs

debugging-apex-logs：Salesforce デバッグログの分析とトラブルシューティング

ユーザーがデバッグログに基づく根本原因分析を必要としている場合に、このスキルを使用します。対象には、ガバナ制限の診断、スタックトレースの解釈、低速クエリの調査、ヒープ／CPU 負荷の分析、ログの証拠に基づく再現から修正までの反復が含まれます。

このスキルが担当するタスク

次の作業では debugging-apex-logs を使用します。

• Salesforce の .log ファイル
• スタックトレースと例外の分析
• ガバナ制限
• SOQL／DML／CPU／ヒープのトラブルシューティング
• ログから抽出したクエリプランやパフォーマンスの証拠

次の場合は別のスキルに委任します。

• Apex テストの実行または修復 → running-apex-tests
• コード修正の生成または実装 → generating-apex
• Agentforce セッショントレース／parquet テレメトリのデバッグ → observing-agentforce

---

最初に収集する必要があるコンテキスト

次の情報を尋ねるか、推測します。

• 組織のエイリアス
• 失敗したトランザクション／ユーザーフロー／テスト名
• おおよそのタイムスタンプまたはトランザクションの時間帯
• 分かる場合はユーザー／レコード／リクエスト ID
• 目標が診断のみか、診断と修正の反復か

---

推奨ワークフロー

1. ログを取得する

references/cli-commands.md のコマンドを使用して、対象組織のログを一覧表示、ダウンロード、またはストリーミングします。

2. 次の順序で分析する

1. エントリーポイントとトランザクションの種類
2. 例外／致命的なエラー
3. ガバナ制限
4. 繰り返される SOQL／DML パターン
5. CPU／ヒープのホットスポット
6. コールアウトのタイミングと外部サービスの障害

3. 重大度を分類する

• Critical — 実行時エラー、ハードリミット、破損のリスク
• Warning — 制限値に近い、非選択的なクエリ、低速な処理経路
• Info — 最適化の機会または衛生上の問題

ワークフローの詳細：references/analysis-playbook.md

---

特に有用な問題パターン

問題	主な兆候	基本的な修正方針
ループ内の SOQL	繰り返し呼び出される処理経路で SOQL_EXECUTE_BEGIN が繰り返される	クエリを一度だけ実行し、マップ／グループ化したコレクションを使用する
ループ内の DML	DML_BEGIN パターンが繰り返される	行を収集し、DML を一度に一括実行する
非選択的なクエリ	スキャン対象行数が多い／選択性が低い	インデックス付きフィルターを追加し、対象範囲を絞る
CPU 負荷	CPU 使用量が同期処理の制限に近づいている	アルゴリズムの複雑さを抑え、キャッシュを使用し、可能であれば非同期処理にする
ヒープ負荷	ヒープ使用量が同期処理の制限に近づいている	SOQL の for ループでストリーミングし、メモリ内データを減らす
Null ポインター／致命的なエラー	EXCEPTION_THROWN／FATAL_ERROR	null の可能性を考慮し、クエリ結果が空の場合の処理を修正する

詳細な例：references/common-issues.md

---

出力形式

分析を終えたら、次の順序で報告します。

1. 何が失敗したか
2. どこで失敗したか（クラス／メソッド／行／トランザクションの段階）
3. なぜ失敗したか（症状だけでなく根本原因）
4. 重大度
5. 推奨する修正
6. 検証手順

推奨される形式：

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

---

ルール／制約

ルール	理由
修正の推奨は必ずログの証拠に基づける	推測による診断を避け、根本原因をログから追跡できるようにします
見つかった問題ごとに、出力項目を6つすべて報告する	各問題について、実行可能で網羅的な調査結果を確保します
調査結果をすべて Critical、Warning、Info のいずれかに分類する	ユーザーが対応する問題の優先順位を付けやすくします
コード生成は generating-apex に委任する	このスキルは診断を行いますが、Apex コードは書き換えません
テストの実行は running-apex-tests に委任する	このスキルはテストクラスの実行も修復も行いません
LIMIT_USAGE イベントを読まずに、制限が安全だと決めつけない	失敗箇所の前に行われた処理が制限を消費している場合があります

---

注意点

落とし穴	対処法
ログが 2 MB で切り詰められる	デバッグレベルを下げ（例：ApexCode: INFO、ApexProfiling: FINE）、再取得します
同じ問題が SOQL の問題と CPU の問題の両方として現れる	まず SOQL のループ内実行を修正します。通常、これが二次的な影響として CPU の急増を引き起こします
トレースフラグの設定後にログが表示されない	トレースフラグの ExpirationDate が未来に設定されていることと、正しいユーザーがトレース対象になっていることを確認します
非同期コンテキストでは制限値が変わる	CPU 制限は非同期処理で 60,000 ms、同期処理で 10,000 ms です。制限違反を指摘する前に、トランザクションの種類を確認します
スタックトレースがユーザーコードではなく、フレームワークの行を示している	トリガーハンドラーを越えてコールスタックをたどり、元となるユーザーコードを見つけます

---

スキル間の連携

必要な作業	依頼先	理由
Apex の修正を実装する	generating-apex	コード変更の生成／レビュー
テストで再現する	running-apex-tests	テストの実行とカバレッジの反復
修正をデプロイする	deploying-metadata	デプロイのオーケストレーション
デバッグ用データを作成する	handling-sf-data	対象を絞ったシードデータ／再現用データ

---

参考ファイル一覧

ファイル	参照するタイミング
references/analysis-playbook.md	まずここから読みます。あらゆるデバッグセッションで使える、詳しい手順ごとのワークフローです
references/common-issues.md	SOQL のループ内実行、DML のループ内実行、CPU／ヒープの負荷、ヌルポインターのパターンをすばやく確認できます
references/cli-commands.md	デバッグログの取得、ストリーミング、管理に使う SF CLI コマンドです
references/debug-log-reference.md	イベントタイプの全一覧、ログレベル、ガバナ制限の参照値です
references/log-analysis-tools.md	ツールガイド：Apex Log Analyzer、Developer Console、CLI の grep パターン
references/benchmarking-guide.md	パフォーマンスのベンチマーク手法、ベンチマークデータ、アンチパターンです
references/scoring-rubric.md	分析品質の評価に使う 100 点満点の評価基準です
assets/benchmarking-template.cls	パフォーマンスベンチマークの実行に使う、コピー＆ペースト可能な Anonymous Apex テンプレートです
assets/cpu-heap-optimization.cls	CPU 時間とヒープ割り当てを削減する Apex パターンです
assets/dml-in-loop-fix.cls	DML のループ内実行違反を解消する前後の例です
assets/soql-in-loop-fix.cls	SOQL のループ内実行違反を解消する前後の例です
assets/null-pointer-fix.cls	ヌルポインター例外を防ぐためのパターンです

---

スコアガイド

スコア	意味
90+	優れた修正指針を伴う、エキスパートレベルの分析
80–89	小さな不足点があるものの、良好な分析
70–79	許容範囲ですが、二次的な問題を見落とす可能性があります
60–69	部分的な診断のみ
< 60	不完全な分析