nebula-logger-install について
Salesforce で Nebula Logger を導入し、永続的で検索可能なログを整えるチーム向けのインストール・設定スキルです。パッケージ選択、権限、階層設定、実行時パラメーター、データマスキングを扱います。
主な機能
- 01Unlocked と managed のパッケージ選択肢
- 02権限セットの割り当てガイド
- 03階層型ログ設定
- 04実行時パラメーターの構成
- 05機密データのマスキングルール
活用シーン
- 01組織に導入するパッケージの選定
- 02管理者やログ利用者のアクセス設定
- 03ログ動作と保持期間の調整
- 04保存前の機密値のマスキング
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/nebula-logger-installを入力して読み込まれたか確認します。
詳細
Nebula Logger のインストールと初期設定
System.debug() だけではなく Nebula Logger を使う理由
System.debug() はデバッグ中には便利ですが、本番環境の運用において永続的な可観測性を確保する方法ではありません。
- デバッグログの保持期間は短く、過去の分析に必要なログを検索するのも困難です。
- ビジネスレコード、プロセスのシナリオ、タグを使った検索は、専用のログオブジェクトと比べて機能が限られています。
- Apex、LWC、Aura、Flow、OmniStudio にわたる統一的なアプローチは提供されません。
Nebula Logger を使うと、Salesforce の実行コンテキスト全体で一貫性のある、クエリ可能なログモデルを利用できます。
パッケージの選択：Unlocked と Managed
Nebula Logger は、どちらのパッケージタイプも同じコアメタデータをサポートしていますが、運用モデルは異なります。
| 項目 | Unlocked Package | Managed Package |
|---|---|---|
| 名前空間 | なし | Nebula |
| リリース頻度 | パッチのリリース頻度が高い | リリース頻度が低く、安定性を重視（Managed リリースは年に約 3 回） |
| ソースの可視性 | 組織内でソース全体にアクセス可能 | パッケージ化されたグローバル API サーフェス |
| プラグインフレームワーク | 利用可能 | 現在は利用不可 |
| 機能範囲 | すべての機能（プラグイン、最新の修正） | 一部のみ。Unlocked Package より遅れて提供されます |
| 配布モデル | GitHub を優先する OSS ワークフロー | AppExchange での Managed 配布に適しています |
| 一般的な推奨 | ほとんどすべてのチームでの標準的な選択肢 | 名前空間付きパッケージが必須の場合のみ（ISV／AppExchange での配布、名前空間による分離が必要な組織） |
名前空間付きパッケージが必須でない限り、Unlocked Package から始めてください。Unlocked Package はより多くの機能（プラグインフレームワーク、より迅速なパッチ提供）とソース全体の可視性を備えています。Managed Package は、Nebula 名前空間が必要なケースのために用意されています。
インストール方法
必ず次のページで最新バージョンを確認してください。
Unlocked Package - v4.19.5
- Sandbox のインストールリンク：
https://test.salesforce.com/packaging/installPackage.apexp?p0=04tg7000000IzRdAAK - Production のインストールリンク：
https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg7000000IzRdAAK - Salesforce CLI：
sf package install --wait 20 --security-type AdminsOnly --package 04tg7000000IzRdAAK
Managed Package - v4.19.0
- Sandbox のインストールリンク：
https://test.salesforce.com/packaging/installPackage.apexp?mgd=true&p0=04tg7000000GZbJAAW - Production のインストールリンク：
https://login.salesforce.com/packaging/installPackage.apexp?mgd=true&p0=04tg7000000GZbJAAW - Salesforce CLI：
sf package install --wait 30 --security-type AdminsOnly --package 04tg7000000GZbJAAW
割り当てる権限セット
ロールアウトの一環として、権限セットを割り当てます。リポジトリ内の正確な API 名は次のとおりです。
| 権限セット | 目的 | 主なユーザー |
|---|---|---|
LoggerAdmin | Nebula Logger のデータと機能を完全に制御します | プラットフォーム管理者、サポートリーダー |
LoggerLogViewer | ログとコンソール機能への読み取り専用アクセス | 運用担当者、QA、サポートアナリスト |
LoggerEndUser | 表示範囲を制御した、日常業務に必要な限定的なアクセス | ログの表示が必要なビジネスユーザー |
LoggerLogCreator | ログの生成に必要な最小限のメタデータ／オブジェクトアクセス | インテグレーションユーザー、Experience Cloud コンポーネントユーザー |
LoggerSettings__c の階層を設定する
Nebula Logger は階層型カスタム設定を使用しており、複数のスコープで動作を調整できます。
- 組織のデフォルトの基準値。
- プロファイルレベルの上書き。
- ユーザーレベルの上書き。
オンボーディングでは、次の設定を優先してください。
| 項目 | 制御する内容 |
|---|---|
IsEnabled__c | 有効な階層レベルでのログ動作のグローバルなオン／オフ切り替え |
LoggingLevel__c | ユーザー／プロファイル／組織のコンテキストに適用される最小ログレベル |
DefaultSaveMethod__c | Logger.saveLog() が使用するデフォルトの保存方法 |
DefaultLogPurgeAction__c | 古いログに対するデフォルトのクリーンアップ動作 |
DefaultNumberOfDaysToRetainLogs__c | 生成されたログの保持期間 |
注：古い資料には DefaultLoggingLevel__c と記載されている場合がありますが、このコードベースで有効な項目は LoggingLevel__c です。
LoggerParameter__mdt の確認とカスタマイズ
Nebula Logger には、実行時の横断的な動作を制御する約40件のレコードが登録された LoggerParameter__mdt CMDT が同梱されています。たとえば、どのサポートオブジェクトをクエリするか、タグをどう保存するか、スタックトレースを解析するか、トランザクションの制限を取得するかなどを制御します。初期設定の値はほとんどの組織で推奨されるデフォルト値ですが、特定の意見が反映された設定のため、調整が必要な組織もあります。インストール後に一覧を確認し、自組織に関係する設定を変更してください。これらのレコードで設定できるトレードオフの例をいくつか紹介します。
- SOQL に敏感な組織：Nebula Logger による追加クエリが懸念される場合（たとえば、コードベースが非常に複雑で、すでにトランザクションあたりの100件という SOQL 制限に近い場合）、
QueryUserDataSynchronously、QueryNetworkDataSynchronously、QueryOrganizationDataSynchronously、QueryAuthSessionDataSynchronouslyの各Query*Synchronouslyレコードをfalseにすると、Log__cの挿入時にエンリッチメントクエリが非同期でのみ実行されるようになります。追加のフィールドがまったく不要な場合は、対応するQuery*Dataレコードをfalseにすると、クエリ自体が無効になります。 - CPU に敏感な組織：デフォルトでは
EnableStackTraceParsingとStoreHeapSizeLimitがtrueです。これらをfalseにすると、ログ件数の多い処理で CPU 消費量を抑えられますが、各エントリのスタックトレース解析とヒープ制限の取得が省略され、可観測性が一部低下します。 - コールアウトが制限されている組織：リリース情報を取得するために
api.status.salesforce.comへ非同期コールアウトを行うCallStatusApiは、Salesforce のステータスエンドポイントへのアウトバウンドコールアウトが許可されていない場合や、必要ない場合にfalseに設定できます。 - 機能の切り替え：
EnableTagging、EnableLogEntryEventStream、NormalizeScenarioData、NormalizeTagDataなどのレコードは、サブシステム全体を有効または無効にします。機能が不要で、関連するストレージやトリガーの処理を避けたい場合に便利です。
すべての LoggerParameter__mdt レコードには、制御対象と変更方法を説明するインラインの Description__c フィールドがあります。一覧を暗記するのではなく、Setup または Logger Console でレコードを開いて説明を確認してください。これらのレコードを変更した場合は動作が変わるものとして扱い、変更の影響を受けるテストを再実行してください。nebula-logger-testing-your-code の「Nebula Logger の CMDT レコードはテストで有効です」セクションを参照してください。
LogEntryDataMaskRule__mdt によるデータマスキングの確認
Nebula Logger には、データを永続化する前に正規表現で機密情報をマスキングする、LogEntryDataMaskRule__mdt レコードの小規模なスターターカタログも同梱されています。レコードは SocialSecurityNumber、VisaCreditCardNumber、MastercardCreditCardNumber、AmericanExpressCreditCardNumber です。各レコードには次の項目があります。
SensitiveDataRegEx__c- 機密情報を含む部分文字列に一致する正規表現です。ReplacementRegEx__c- 置換パターンです（通常は前後の文脈を残し、中央の数字をマスキングします）。ApplyToMessage__c/ApplyToRecordJson__c- ログエントリのメッセージテキスト、.setRecord(...)で取得したRecordJson__c、またはその両方にルールを適用するかどうかを指定します。IsEnabled__c- レコードを削除せずに有効・無効を切り替えます。
同梱のルールは妥当な基本設定ですが、すべてのパターンを網羅しているわけではありません。独自の機密情報パターンを持つドメインデータ（顧客 ID、米国以外の国民 ID 番号、API トークン、内部案件番号など）をログに記録する組織では、開発者が Logger.info(...) の呼び出し前に値を手動で削除することに頼らず、それらのパターンに対応する LogEntryDataMaskRule__mdt レコードを追加でデプロイしてください。リリース前に、代表的な文字列に対して正規表現をテストしてください。貪欲すぎるパターンは無関係な部分文字列を壊す可能性があり、狭すぎるパターンでは機密情報がそのまま残る可能性があります。
最初のトラブルシューティング項目
デプロイ後にログが作成されない場合は、まず権限セットの割り当てを確認してください。特に LoggerEndUser（コンポーネントやインテグレーションのコンテキストでは LoggerLogCreator）を確認します。権限の不足は、インストール後に最もよく発生する問題です。
次のステップ
Nebula Logger のインストールと権限設定が完了したら、多くのチームでは次のいずれかに進みます。
- ロギングを開始する - Apex、LWC、Aura、Flow、OmniStudio に対応した API については、nebula-logger-instrumentation を参照してください。
- 保持期間を設定する -
LogBatchPurgerのスケジュール設定と保持日数の構成については、nebula-logger-purging-and-retention を参照してください。 - チームの標準を取り入れる - 環境に応じたログレベルとレビュー時のガードレールについては、nebula-logger-best-practices を参照してください。
- 既存のログを調査する - コンソールアプリとそのリストビューについては、nebula-logger-console を参照してください。