mcpField
P
platform-apex-logs-debug

platform-apex-logs-debug

github.com/forcedotcom開発1.1k6.9k 回インストール1 日前に更新
リポジトリ

platform-apex-logs-debug について

Apex デバッグログから例外、ガバナ制限、性能上のボトルネックを診断する Salesforce 向けスキルです。ログの証拠に基づく原因分析と検証手順を示します。

主な機能

  1. 01例外とスタックトレースの解釈
  2. 02ガバナ制限の使用状況確認
  3. 03繰り返される SOQL と DML の検出
  4. 04CPU とヒープ負荷の調査
  5. 05証拠に基づく修正案

活用シーン

  1. 01失敗した Salesforce トランザクションの診断
  2. 02ループ内の SOQL や DML の調査
  3. 03CPU またはヒープ制限の分析
  4. 04NullPointer の原因追跡

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-apex-logs-debug

インストール後、Claude Code で/platform-apex-logs-debugを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
assets/
benchmarking-template.cls
cpu-heap-optimization.cls
dml-in-loop-fix.cls
null-pointer-fix.cls
soql-in-loop-fix.cls
references/
analysis-playbook.md
benchmarking-guide.md
cli-commands.md
common-issues.md
debug-log-reference.md
log-analysis-tools.md
scoring-rubric.md

詳細

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

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

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

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

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

次の場合は、ほかのスキルに委任します。

最初に収集する必須コンテキスト

次の情報を確認するか、推定します。

  • org エイリアス
  • 失敗したトランザクション／ユーザーフロー／テスト名
  • おおよそのタイムスタンプまたはトランザクションの時間帯
  • 判明している場合はユーザー／レコード／リクエスト ID
  • 目的が診断のみか、診断から修正までのループか

推奨ワークフロー

1. ログを取得する

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

2. 次の順序で分析する
  1. エントリーポイントとトランザクションの種類
  2. 例外／致命的なエラー
  3. ガバナ制限
  4. 繰り返される SOQL／DML パターン
  5. CPU／ヒープのホットスポット
  6. コールアウトのタイミングと外部エラー
3. 重大度を分類する
  • Critical — 実行時の失敗、ハードリミット、破損のリスク
  • Warning — 制限値に近い状態、非選択的クエリ、遅い処理経路
  • Info — 最適化の機会またはコード衛生上の問題
4. 適切な最小限の修正を提案する

次のような修正を優先します。

  • 根本原因に対処する
  • 一括処理に安全である
  • テスト可能である
  • 再実行で簡単に検証できる

拡張ワークフロー：references/analysis-playbook.md

重大な問題の典型パターン

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

詳細な例：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 のいずれかに分類するユーザーが、どの問題から対処すべきか優先順位を付けやすくするため
コード生成は platform-apex-generate に委任するこのスキルは診断を行いますが、Apex コードを書き換えることはありません
テスト実行は platform-apex-test-run に委任するこのスキルではテストクラスを実行または修復しません
LIMIT_USAGE イベントを確認せずに、制限に余裕があると決めつけない失敗箇所のログに現れない先行処理によって、制限が消費されている場合があります

落とし穴

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

スキル間の連携

必要な作業委任先理由
Apex の修正を実装するplatform-apex-generateコード変更の生成／レビュー
テストで再現するplatform-apex-test-runテスト実行とカバレッジの反復
修正をデプロイするplatform-metadata-deployデプロイのオーケストレーション
デバッグデータを作成するplatform-data-manage対象を絞ったシードデータ／再現データ
遅い SOQL クエリを最適化するplatform-soql-queryクエリ構造／パフォーマンスのチューニング

参照ファイル一覧

ファイル読むタイミング
references/analysis-playbook.mdまずはこちらを参照してください。あらゆるデバッグセッションの詳細な手順を記載しています
references/common-issues.mdSOQL のループ内実行、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.clsCPU 時間とヒープ割り当てを削減する Apex パターン
assets/dml-in-loop-fix.clsDML のループ内実行違反を解消する修正前／修正後の例
assets/soql-in-loop-fix.clsSOQL のループ内実行違反を解消する修正前／修正後の例
assets/null-pointer-fix.clsヌルポインター例外を防ぐためのパターン

スコアガイド

スコア意味
90+修正の指針が明確な、専門的な分析
80–89小さな抜けはあるものの、良質な分析
70–79許容できるが、二次的な問題を見落とす可能性がある
60–69部分的な診断のみ
< 60不完全な分析

コメント

Markdown 対応