关于 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 安装与初始配置
为什么选择 Nebula Logger，而不是只用 System.debug()
System.debug() 在主动调试时很有用，但它并非适用于生产运营的持久化可观测性方案。
- 调试日志的保留期限很短，而且难以查询以进行历史分析。
- 与专门设计的日志对象相比，按业务记录、流程场景或标签搜索的能力有限。
- 它无法在 Apex、LWC、Aura、Flow 和 OmniStudio 之间提供统一的方法。
Nebula Logger 为团队提供了一套一致且可查询的日志记录模型，适用于各种 Salesforce 运行时环境。
软件包选择：非锁定软件包与托管软件包
Nebula Logger 支持这两种软件包类型，核心元数据相同，但运作模式有所不同。
| 领域 | 非锁定软件包 | 托管软件包 |
|---|---|---|
| 命名空间 | 无 | Nebula |
| 发布节奏 | 补丁发布更频繁 | 发布节奏较慢且稳定（每年大约发布三个托管版本） |
| 源码可见性 | 可在组织中访问全部源码 | 打包后的全局 API 表面 |
| 插件框架 | 可用 | 目前不可用 |
| 功能覆盖范围 | 所有功能（插件、最新修复） | 部分功能，落后于非锁定软件包 |
| 分发模式 | 以 GitHub 为先的 OSS 工作流 | 适合通过 AppExchange 分发的托管交付 |
| 典型建议 | 几乎所有团队的默认选择 | 仅在硬性要求使用带命名空间的软件包时选择（ISV / AppExchange 交付、要求隔离命名空间的组织） |
除非硬性要求使用带命名空间的软件包，否则请从非锁定软件包开始。非锁定软件包功能更多（插件框架、补丁发布更快），且源码完全可见；托管软件包专为需要 Nebula 命名空间的情况而提供。
安装选项
请务必在以下网址确认最新版本：
非锁定软件包 - 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
托管软件包 - 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 查询的上限），可以将
Query*Synchronously记录（QueryUserDataSynchronously、QueryNetworkDataSynchronously、QueryOrganizationDataSynchronously、QueryAuthSessionDataSynchronously）设为false，这样只有在插入Log__c时才会异步执行数据丰富查询。将对应的Query*Data记录设为false，则会完全禁用查询（如果完全不需要这些额外字段）。 - 对 CPU 敏感的组织：默认情况下，
EnableStackTraceParsing和StoreHeapSizeLimit均为true。将它们设为false，可跳过逐条解析堆栈跟踪和捕获堆限制，从而以牺牲部分可观测性为代价，降低高容量日志路径的 CPU 消耗。 - 限制 Callout 的组织：如果不允许或不希望向 Salesforce 状态端点发出出站 Callout，可将
CallStatusApi（用于获取版本信息、向api.status.salesforce.com发起的异步 Callout）设为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、美国境外的国民身份证号码、API 令牌、内部案例编号等）的组织，都应为这些模式部署额外的 LogEntryDataMaskRule__mdt 记录，而不是指望开发人员在调用 Logger.info(...) 前记得手动剔除这些值。发布前请使用有代表性的字符串测试正则表达式：模式过于宽泛可能会破坏无关子字符串，过于狭窄则可能让敏感值漏过。
首先排查的问题
如果部署后未创建日志，请先检查权限集分配，尤其是 LoggerEndUser（或在组件／集成场景中检查 LoggerLogCreator）。缺少权限是安装后最常见的问题。
后续步骤
安装并配置好 Nebula Logger 的权限后，大多数团队接下来会选择：
- 开始记录日志 - 参阅 nebula-logger-instrumentation，了解 Apex、LWC、Aura、Flow 和 OmniStudio 的 API。
- 设置保留策略 - 参阅 nebula-logger-purging-and-retention，了解
LogBatchPurger的调度和保留天数配置。 - 采用团队规范 - 参阅 nebula-logger-best-practices，了解根据环境设置日志级别和审核防护措施。
- 排查现有日志 - 参阅 nebula-logger-console，了解控制台应用及其列表视图。