nebula-logger-purging-and-retention

Nebula Logger 中的日志保留与清除

保留模型

每条 Log__c 记录都有一个 LogRetentionDate__c。该日期过后，日志即可由 LogBatchPurger 清除。插入 Log__c 时，保留日期根据以下内容设置：

• 生效层级记录上的 LoggerSettings__c.DefaultNumberOfDaysToRetainLogs__c。
• 可选的 LoggerScenarioRule__mdt.NumberOfDaysToRetainLogs__c，适用于日志场景与某条场景规则匹配的情况（场景专属设置优先于层级默认值）。

如果未配置保留天数，LogRetentionDate__c 将保持为 null，日志永远不会自动清除。

LoggerSettings__c 保留字段

LoggerSettings__c 中与保留相关的部分属于层级自定义设置，值按组织默认值 -> 配置文件 -> 用户的顺序逐级继承。相关字段如下：

字段	用途
DefaultNumberOfDaysToRetainLogs__c	从日志插入到可清除之间的天数。Null = 不自动清除。
DefaultLogPurgeAction__c	批处理作业处理符合清除条件的日志时执行的操作。默认值为 Delete。
IsEnabled__c	总开关；在某个层级禁用日志记录，也会停止为该层级的用户写入新的 Log__c 记录。

清除操作

Log__c.LogPurgeAction__c（插入时根据 LoggerSettings__c.DefaultLogPurgeAction__c 填充）用于告知 LogBatchPurger 如何处理到期日志：

• Delete（默认）：批处理作业会硬删除 Log__c 及其子级 LogEntry__c 记录。它们不会进入回收站。
• 插件提供的操作：某些 Nebula Logger 插件会添加自己的清除操作。例如，big-object-archiving 插件会在删除日志前将其复制到大对象中，以便长期查询数据。安装此类插件后，其清除操作便会成为 LogPurgeAction__c 的有效值。

安排清除作业

LogBatchPurger 不会自动运行。请通过 LogBatchPurgeScheduler 安排它：

// Run daily at 2am - adjust the cron expression for your org
String cronExpression = '0 0 2 * * ?';
System.schedule('Nebula Logger - Daily Purge', cronExpression, new LogBatchPurgeScheduler());

LogBatchPurgeScheduler 提供无参构造函数以使用默认批处理大小，也提供 LogBatchPurgeScheduler(Integer batchSize) 构造函数以调整处理吞吐量。

如果未安排作业，新日志仍会正确设置 LogRetentionDate__c，但不会有任何日志被清除。“我们将保留期设为 30 天，但六个月前的日志仍然存在”这种情况，最常见的原因就是没有安排清除作业。

按场景设置保留期

若要让某些业务流程的日志保留时间长于（或短于）默认值，请创建一条 LoggerScenarioRule__mdt 记录，其 Scenario__c 与传入 Logger.setScenario(...) 的值匹配。设置：

• IsEnabled__c = true（否则规则不会生效）。
• IsLogRetentionOverrideEnabled__c = true（这是实际启用保留期覆盖的开关；若此标志关闭，仅设置 NumberOfDaysToRetainLogs__c 不会产生任何作用）。
• NumberOfDaysToRetainLogs__c = 匹配此场景的日志目标保留天数。

对于受监管的流程（“财务审计日志保留 7 年”）或高日志量的测试场景（“集成冒烟测试日志在 24 小时后清除”），请使用场景规则，而不要尝试全局调整层级设置。

按用户 / 按配置文件保留

由于 LoggerSettings__c 是分层自定义设置，因此可以按用户或配置文件调整保留策略。常见模式：

• 调试用户保留更久：为开发人员配置文件设置更长的 DefaultNumberOfDaysToRetainLogs__c，避免调查工作所需的日志被清除。
• 高容量集成用户保留更短：为集成用户配置文件设置更短的保留期限，避免其（多得多的）日志量占用过多存储空间。

在这些配置文件的 LoggerSettings__c 中设置配置文件级别的值；其他用户则继承组织默认值。

验证保留设置

在确认保留策略正常工作之前，请在目标组织中验证以下三项：

1. 组织默认级别的 LoggerSettings__c 已设置非空的 DefaultNumberOfDaysToRetainLogs__c。
2. 已安排 LogBatchPurgeScheduler（在 Setup -> Scheduled Jobs 中检查）。
3. 新建的 Log__c 记录已填充 LogRetentionDate__c。快速测试日志，然后查询 SELECT Id, LogRetentionDate__c FROM Log__c ORDER BY CreatedDate DESC LIMIT 1。

如果缺少以上任何一项，保留策略实际上就没有生效。

存储注意事项

• Log__c 和 LogEntry__c 会计入自定义对象存储。通常，LogEntry__c 是存储量的主要来源（每条日志包含许多条目）。
• 较高的 LoggerSettings__c.LoggingLevel__c 值（FINE、FINER、FINEST）会产生多得多的条目。结合适合环境的日志级别和保留期限来控制存储增长——参见 nebula-logger-best-practices。
• 如果存储确实成为限制，可以缩短保留期限、提高生产环境中的日志级别阈值，或安装 big-object-archiving 插件，将过期数据转移到大对象中。

相关技能

• nebula-logger-install - 初始配置 LoggerSettings__c。
• nebula-logger-best-practices - 与保留策略相配合、适应不同环境的日志级别。
• nebula-logger-plugin-development - 构建自定义清理操作插件（例如，归档到外部系统）。