nebula-logger-best-practices

Nebula Logger のベストプラクティスとガバナンス

チーム全体でのプラクティス

プルリクエストをレビューするときや、ロギング規約を設計するときは、これらのデフォルトを使用してください。

1. ERROR、WARN、INFO は、運用上重要な情報にのみ使用します。
2. 大量の診断情報には DEBUG、FINE、FINER、FINEST を使用します。これらは LoggerSettings__c.LoggingLevel__c と組み合わせることで、本番環境では実行時のオーバーヘッドを増やさずにコード内に残しておき、より詳細な診断が必要な場合にのみ有効化できます。
3. 環境に応じて LoggerSettings__c のデータを調整します。
   • 本番組織では LoggingLevel__c を ERROR、WARN、INFO に設定してログのノイズを減らします（デバッグ時は DEBUG、FINE、FINER、FINEST に変更します）。
   • スケジュール済みの削除と保持期間（DefaultLogPurgeAction__c、DefaultNumberOfDaysToRetainLogs__c）を設定します。
4. ビジネスプロセスごとにグループ化するには、静的メソッド Logger.setScenario() と、インスタンスメソッド LogEntryEventBuilder.addTag() および LogEntryEventBuilder.addTags() を使用します。
   • チームにとって分かりやすい、シナリオとタグの統一された命名規則を定めます。
5. メッセージ文字列に追加データを直接埋め込むのではなく、LogEntryEventBuilder のインスタンスメソッドを使用してデータをさらに補足します。次のようなメソッドオーバーロードを利用できます。
   • .setExceptionDetails(...)
   • .setApprovalResult(...)
   • .setDatabaseResult(...)
   • .setRecord(...)
   • .setHttpRequestDetails(...)
   • .setHttpResponseDetails(...)
   • .setRestRequestDetails(...)
   • .setRestResponseDetails(...)
   • .setField(...)
6. Logger.saveLog() は意図的に呼び出します。ログエントリごとに呼び出したり、タイトなループの中で呼び出したりしてはいけません。Apex で DML を呼び出す場合と同様に、戦略的に呼び出してください。
   • Logger.info(...)、.error(...) などは、エントリをメモリ内バッファーに追加するだけです。saveLog() が実行されるまで、データは永続化されません。saveLog() を呼び出さずにトランザクションが終了すると、バッファー内のデータはすべて失われます。そのため、トランザクションがコミットされる前に saveLog() を呼び出す必要があります。
   • saveLog() を呼び出すたびに、実際のコストが発生するプラットフォーム操作が行われます。デフォルトの保存方法 EVENT_BUS では、saveLog() を呼び出すたびに System.EventBus.publish(List<LogEntryEvent__e>) が 1 回呼び出されます。これにより、System.Limits.getLimitPublishImmediateDML() の上限（1 トランザクションあたり 100 回）に対して 1 回分が消費され、組織の日次プラットフォームイベント発行割り当ても 1 回分消費されます。ほかの保存方法にもそれぞれ上限があります。QUEUEABLE は非同期ジョブの枠（System.Limits.getLimitQueueableJobs()）を消費し、REST はコールアウトを消費し、SYNCHRONOUS_DML は通常の DML 行数とステートメント数を消費します。いずれも無料ではありません。
   • 1 つのトランザクションで saveLog() を複数回呼び出しても問題なく、適切な場合もよくあります。中間状態を保存する妥当なタイミングには、バッチ内の各チャンクの処理後、長時間実行されるループの外側スコープで各反復の終了時（内側スコープでは決して呼び出さないでください。以下を参照）、非同期処理への引き渡し前（Queueable／Future／Batchable）、再スローする予定の例外を捕捉する finally ブロック内などがあります。保存のたびに、その時点でバッファーにあるデータだけが発行されるため、後続のトランザクション処理が失敗しても、そのエントリは永続化されます。
   • 問題なのは、ログエントリを 1 つ追加するたびに saveLog() を呼び出すことです。これでは N 回のログ呼び出しが N 回のプラットフォームイベント発行に変わり、getLimitPublishImmediateDML()（1 トランザクションあたり 100 回）をすぐに使い切り、運用上の利点がないまま組織の日次プラットフォームイベント割り当ても消費します。Logger.info(...); Logger.saveLog(); を繰り返し記述している場合は、エントリをバッファーに追加して、グループの処理後に 1 回保存してください。
   • レコードを処理するループの最も内側の本体では、saveLog() を決して呼び出さないでください。ループ内ではエントリをバッファーに追加し、各レコードの処理後ではなく、ループの後（または N 回の反復後、チャンクの処理後など、安全なチェックポイント）に saveLog() を呼び出します。
   • トランザクション処理のコードパスでは、例外が try から抜けても実行されるよう、finally ブロック内に Logger.saveLog() を配置します。そのコードパスでデフォルトの EVENT_BUS が適切でない場合は、メソッドの先頭で Logger.setSaveMethod(...) と組み合わせてください（上記の保存方法に関する説明を参照）。

環境に応じたログレベル

ログの詳細度はコード定数ではなく、運用上の制御項目として扱います。

環境	推奨される基本設定	理由
Production	ERROR または WARN	インシデントの兆候を維持しながら、ノイズとストレージへの影響を軽減します
UAT	INFO	過剰な詳細情報を避けながら、ビジネスフローを検証します
QA	DEBUG または FINE	不具合の再現と統合テストを支援します
Sandbox/Dev	FINE から FINEST（期間限定）	開発中の詳細な診断に役立ちます

一時的なインシデント対応期間には階層オーバーライド（ユーザー／プロファイル）を使用し、その後は元に戻します。

既存コードのレビュー用チェックリスト

• 各実行パスで、意図的に設定したチェックポイントで saveLog() を呼び出していますか？ エントリごと、またはレコード単位の内部ループ内で呼び出していませんか？
• 例外はスタックトレースのコンテキストとともに記録されていますか？
• .setRecord(...) を介してレコード参照を設定していますか？
• シナリオとタグはチームの分類体系に沿っていますか？
• デフォルトの EVENT_BUS を使わない場合、保存メソッドを明示的に選択していますか？

ガバナーと容量に関する考慮事項

Nebula Logger は可観測性の向上に役立ちますが、Salesforce のガバナー制限の範囲内で実行されます。

制約	ロギングへの影響	対策
データストレージ	大量のログによってカスタムオブジェクトのストレージがすぐに消費される可能性があります	保持ポリシーと削除スケジュールを適用し、本番環境ではログの詳細度を下げます
プラットフォームイベントの日次上限	EVENT_BUS の量が組織のイベント割り当て上限に達する可能性があります	ログを選択的に記録し、必要に応じて対象ジョブを QUEUEABLE／SYNCHRONOUS_DML に切り替えます
SOQL クエリ	ロギングパスで追加される補足クエリによって制限がさらに厳しくなる可能性があります	クエリ済みのレコードを再利用し、ログ専用のクエリ増加を避けます
CPU 時間	ループ内での重いシリアライズやタグ付けにより CPU 使用量が増加します	反復ごとではなく集約したマイルストーンを記録し、非同期の保存パスを優先します
非同期ジョブの割り当て	QUEUEABLE を使いすぎると、ビジネス上の非同期処理と競合する可能性があります	キュー可能な保存処理は、コストの高いコンテキストや混合 DML の影響を受けやすいコンテキストに限定します
ヒープサイズ	大きなペイロードや例外によってトランザクションメモリが膨張する可能性があります	サイズ超過のペイロードを切り詰め、オブジェクトグラフ全体の出力を避けます

Nebula Logger を使わない場合

Nebula Logger は、適切なアーキテクチャの代替にはなりません。

• 不明瞭なドメイン設計の回避策としてロギングを使用しないでください。
• ログメッセージにシークレット、認証情報、または不要な PII を保存しないでください。

Nebula Logger は、明確なサービス境界、堅牢なエラーハンドリング、目的に沿ったテレメトリと組み合わせ、構造化された可観測性レイヤーとして使用してください。