Configuration

LesliAudit reads its settings from Lesli.config.audit. Override only the values that differ from the defaults and merge them with the existing hash so future engine defaults are preserved:

# config/initializers/lesli.rb
Lesli.configure do |config|
  config.audit = config.audit.merge(
    enable_logs: true,
    enable_journals: true,
    enable_analytics: true,
    analytics_retention_days: 400,
    traffic_retention_days: 400,
    audit_retention_days: nil
  )
end

Settings

Setting Type Default Behavior
enable_logs Boolean true Enables explicit account and user activity events
enable_journals Boolean true Records individual requests as user journal history while analytics is enabled
enable_analytics Boolean true Master switch for request counters, journals, and successful-login device aggregates
analytics_retention_days Positive integer or nil 400 Retention period for authenticated request counters, journals, and successful-login device aggregates
traffic_retention_days Positive integer or nil 400 Retention period for provider traffic snapshots and Cloudflare synchronization history
audit_retention_days Positive integer or nil nil Retention period for append-only activity events

Cloudflare Traffic configuration lives under config.audit[:cloudflare]:

config.audit[:cloudflare] = {
  enabled: true,
  zone_id: ENV["CLOUDFLARE_ANALYTICS_ZONE_ID"],
  hostnames: [ "www.example.com" ],
  account_ids: [ 1 ],
  page_size: 1_000,
  max_pages: 100,
  backfill_days: 30,
  reimport_days: 3,
  resource_resolver: ->(account:, hostname:, path:) {
    # Return { resource_type: "Profile", resource_id: 27 } or nil.
  }
}

Store the token in cloudflare.analytics.token in Rails credentials or in the CLOUDFLARE_ANALYTICS_TOKEN environment variable. The resolver belongs to the host because only the host knows which application record owns a URL path.

nil disables automatic cleanup for that data class. Invalid retention values raise ArgumentError when cleanup runs. Keep audit_retention_days unset until the host application has defined its legal-hold, export, and deletion policy.

Analytics and Journal Modes

enable_analytics is the master switch. enable_journals controls whether individual request details are retained while analytics is enabled:

Analytics Journals Result
Enabled Enabled Update request aggregates and record the individual request journal
Enabled Disabled Update request aggregates without creating a journal
Disabled Enabled Do not capture request analytics or journals
Disabled Disabled Do not capture a request event

Explicit activity events are controlled only by enable_logs; the analytics switches do not affect them. Traffic has no capture switch because providers write through an explicit importer rather than an automatic request callback.

Retention Domains

The three retention settings follow the report concepts directly:

  • analytics_retention_days applies to Analytics and Requests data, including both retained and transient journals;
  • traffic_retention_days applies to Traffic snapshots and Cloudflare synchronization history;
  • audit_retention_days applies only to the append-only events shown in Logs.

Retention Cleanup Job

Schedule LesliAudit::RetentionCleanupJob once per day after choosing retention periods. LesliAudit intentionally does not select a scheduler or queue because those are host-application concerns. See Tasks for the equivalent manual cleanup command.

Optional Engines

LesliShield is optional. When installed, its session identifier is recorded as opaque metadata; LesliAudit does not create a foreign key to Shield tables.

LesliDashboard is also optional. Its installation does not change audit capture or retention. See Dashboards when enabling the Audit dashboard component.

 Edit this page

Last Update: 2026/10/29