rails_audit_log 0.9.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9a9fcdb866f5300a3a2fd9bd6026ad93530d15b0b26d771ef1a28a47985280
-  data.tar.gz: 01ac4b3f95fd1c2067a8aa5936122ff86dc264fe771881515dd31d3401377b66
+  metadata.gz: 26fdf8335990094a7278cbcf9921e123fbf44f6ec464b974b1c73e1f41047691
+  data.tar.gz: 9700fef384bb8f23eb929b0c62cb82880ba8217a44f64660f97823c4ffe6f1c0
 SHA512:
-  metadata.gz: 4c155747f1219996a6fde0fcc0d00c764df0f296c7b099418b7020ef90984690400300174b5c1cc1dc4842451a3f53d35e4b710542693683c78d4706c0eca1c1
-  data.tar.gz: 256ef73b739193443718481ef7fa1c0920ae4b4d424e3466b9ac3dbaf9a0bf8b7cf4823d0fd7d000652710985ac60fa6df6252e5997266bb40eda6bde9ba9941
+  metadata.gz: 8c0450b8f9228ec6ea98e7e026e0554d73004accf1a284433fa6260b5acd941d8314fd33b9bf873156e214f65f8bcd1d687613077f60c310dacd2a2b4e1f98e8
+  data.tar.gz: 733c560b234f96900a760cc76b74a18bd39303179e36ae8272c0f150560139272eb3fb0de9ee435883fbd2c128bd408b373601f407818ff9e5c72cb9c465e503

data/README.md

@@ -6,10 +6,47 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://www.ruby-lang.org)
 [![codecov](https://codecov.io/gh/eclectic-coding/rails_audit_log/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/rails_audit_log)
 
-A modern, Zeitwerk-native Rails engine for auditing ActiveRecord changes. Tracks `create`, `update`, and `destroy` events with JSON-first storage, whodunnit actor context, and a clean query API.
+Audit logging for Rails. Tracks `create`, `update`, and `destroy` events as structured JSON records with a mountable web dashboard, whodunnit actor context, batch writes, time-travel reconstruction, and test helpers — a clean, well-documented replacement for PaperTrail with a built-in migration path.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Web dashboard](#web-dashboard)
+- [Usage](#usage)
+  - [Tracking a model](#tracking-a-model)
+  - [Recording who made the change](#recording-who-made-the-change)
+  - [Actor context outside of controllers](#actor-context-outside-of-controllers)
+  - [Querying the audit log](#querying-the-audit-log)
+  - [Lightweight queries](#lightweight-queries)
+  - [Association tracking](#association-tracking)
+  - [Bulk audit writes](#bulk-audit-writes)
+  - [Async audit writes](#async-audit-writes)
+  - [Capping history per record](#capping-history-per-record)
+  - [Time-based retention](#time-based-retention)
+  - [Scheduled and manual pruning](#scheduled-and-manual-pruning)
+  - [Selective tracking](#selective-tracking)
+  - [Disabling auditing](#disabling-auditing)
+  - [Object reconstruction](#object-reconstruction)
+  - [Attaching a reason](#attaching-a-reason)
+  - [Arbitrary metadata](#arbitrary-metadata)
+  - [Request metadata capture](#request-metadata-capture)
+  - [Actor display name snapshot](#actor-display-name-snapshot)
+  - [Object snapshot storage](#object-snapshot-storage)
+  - [Separate audit database](#separate-audit-database)
+  - [Test helpers](#test-helpers)
+- [Stability and versioning](#stability-and-versioning)
+- [Migrating from PaperTrail](#migrating-from-papertrail)
+- [Performance](#performance)
+- [Companion gems](#companion-gems)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
+[↑ Table of contents](#table-of-contents)
+
 Add to your `Gemfile`:
 
 ```ruby
@@ -23,16 +60,72 @@ bin/rails generate rails_audit_log:install
 bin/rails db:migrate
 ```
 
-Optionally scaffold a commented initializer with every configuration option:
+## Configuration
+
+[↑ Table of contents](#table-of-contents)
+
+Run the initializer generator to create `config/initializers/rails_audit_log.rb` with every option documented as a commented example:
 
 ```bash
 bin/rails generate rails_audit_log:initializer
 ```
 
-This creates `config/initializers/rails_audit_log.rb` with all settings documented as commented examples inside a `RailsAuditLog.configure` block.
+The generated file (shown below with all options) uses the block-style `configure` API. Every setting has a sensible default — uncomment only what you need:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+
+RailsAuditLog.configure do |config|
+  # Global columns excluded from all audited models.
+  # Default: ["updated_at"]
+  # config.ignored_attributes = %w[updated_at cached_at]
+
+  # Store a full attribute snapshot alongside object_changes.
+  # Default: true
+  # Disable to save storage; reify and version_at fall back to diff-only reconstruction.
+  # config.store_snapshot = false
+
+  # Capture remote_ip and user_agent into each entry's metadata column.
+  # Default: false — requires RailsAuditLog::Controller in ApplicationController.
+  # config.capture_request_metadata = true
+
+  # Customise how the actor's display name is stored at write time.
+  # Default: actor.name if available, otherwise actor.to_s
+  # config.whodunnit_display = ->(actor) { actor.email }
+
+  # Global cap on entries retained per tracked record. nil = no limit.
+  # Per-model `audit_log version_limit: N` takes precedence.
+  # config.version_limit = 100
+
+  # Global time-based TTL — entries older than this duration are pruned after
+  # each write. Composes with version_limit: an entry is removed when it
+  # exceeds either constraint. Default: nil (no TTL)
+  # config.retention_period = 90.days
+
+  # Write all audit entries asynchronously via WriteAuditLogJob.
+  # Default: false — per-model `audit_log async: true` also works.
+  # config.async = true
+
+  # Route AuditLogEntry to a dedicated database (Rails multi-DB).
+  # config.connects_to = { database: { writing: :audit_log, reading: :audit_log } }
+
+  # Entries per page in the web dashboard. Default: 25
+  # config.page_size = 50
+
+  # Gate web dashboard access. Block runs in controller context so controller
+  # helpers like current_user are available directly. Falls back to HTTP Basic
+  # auth when the block returns falsy. Leave unset for unauthenticated access.
+  # config.authenticate { current_user&.admin? }
+  # config.authenticate { |c| c.current_user&.admin? }
+end
+```
+
+Each option is documented in detail in its own Usage section below.
 
 ## Web dashboard
 
+[↑ Table of contents](#table-of-contents)
+
 Mount the engine in `config/routes.rb` to enable the built-in audit trail browser:
 
 ```ruby
@@ -43,6 +136,8 @@ Then visit `/audit` to browse all audit entries. The dashboard is delivered via
 
 ## Usage
 
+[↑ Table of contents](#table-of-contents)
+
 ### Tracking a model
 
 Include `RailsAuditLog::Auditable` in any ActiveRecord model:
@@ -120,19 +215,6 @@ entry.diff
 # => { "title" => { from: "Hello", to: "World" } }
 ```
 
-### Separate audit database
-
-Route all audit writes to a dedicated database by setting `connects_to` in an initializer. The engine applies it to `AuditLogEntry` at boot:
-
-```ruby
-# config/initializers/rails_audit_log.rb
-RailsAuditLog.connects_to = {
-  database: { writing: :audit_log, reading: :audit_log }
-}
-```
-
-The key (e.g. `:audit_log`) must match a database key in `config/database.yml`. All reads and writes on `AuditLogEntry` — including `batch_audit` inserts and `WriteAuditLogJob` — use that connection automatically.
-
 ### Lightweight queries
 
 Use `.slim` to exclude the three JSON blob columns (`object_changes`, `object`, `metadata`) from the SQL projection. This is useful for index or listing views where you only need the entry header (who, what event, when):
@@ -248,6 +330,45 @@ Set a global default in an initializer — per-model values take precedence:
 RailsAuditLog.version_limit = 50
 ```
 
+### Time-based retention
+
+Automatically prune entries older than a configured duration by setting `retention_period` in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.retention_period = 90.days
+```
+
+Entries whose `created_at` is older than the period are deleted after each write. `retention_period` and `version_limit` compose — an entry is pruned when it exceeds **either** constraint.
+
+Override the global default per model with `retain_for:`:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log retain_for: 30.days  # takes precedence over RailsAuditLog.retention_period
+end
+```
+
+### Scheduled and manual pruning
+
+`RailsAuditLog::PruneAuditLogJob` prunes all audited models in one pass. It iterates over every `item_type` present in `audit_log_entries`, resolves the effective `retain_for` / `retention_period` and `version_limit` per model, and deletes entries that exceed either constraint.
+
+Enqueue it on a recurring schedule via your job backend:
+
+```ruby
+# config/recurring.yml (Solid Queue)
+prune_audit_log:
+  class: RailsAuditLog::PruneAuditLogJob
+  schedule: every day at midnight
+```
+
+Or run it once manually via the rake task:
+
+```bash
+bin/rails rails_audit_log:prune
+```
+
 ### Selective tracking
 
 Track only specific attributes, or exclude noisy ones:
@@ -293,22 +414,20 @@ article.skip_audit_log { article.update!(cached_at: Time.current) }
 
 ### Object reconstruction
 
-#### Reify a single entry
-
-`AuditLogEntry#reify` returns an unsaved ActiveRecord instance reflecting the record's state **before** the entry was recorded:
+**Reify a single entry** — `AuditLogEntry#reify` returns an unsaved ActiveRecord instance reflecting the record's state **before** the entry was recorded:
 
 ```ruby
 article.update!(title: "v2")
 entry = article.audit_log_entries.updated_events.last
 
 previous = entry.reify
-previous.title   # => "v1"  (the pre-update state)
+previous.title      # => "v1"  (the pre-update state)
 previous.persisted? # => false
 ```
 
 Returns `nil` for `create` entries (nothing existed before).
 
-#### Reconstruct state at any point in time
+**Reconstruct state at any point in time:**
 
 ```ruby
 snapshot = RailsAuditLog.version_at(article, 1.week.ago)
@@ -317,7 +436,7 @@ snapshot.title  # => whatever the title was a week ago
 
 Returns `nil` if the record had no history at that time or was already destroyed.
 
-#### Navigate the version chain
+**Navigate the version chain:**
 
 ```ruby
 entry = article.audit_log_entries.updated_events.last
@@ -402,31 +521,58 @@ To save storage at the cost of reduced reification accuracy, switch to diff-only
 RailsAuditLog.store_snapshot = false
 ```
 
-### Test helper
+### Separate audit database
 
-`without_audit_log` silences audit tracking inside the block — useful in FactoryBot factories and seed data to avoid noise in the audit trail:
+Route all audit writes to a dedicated database by setting `connects_to` in an initializer. The engine applies it to `AuditLogEntry` at boot:
 
 ```ruby
-# spec/rails_helper.rb (or spec/support/factory_helpers.rb)
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.connects_to = {
+  database: { writing: :audit_log, reading: :audit_log }
+}
+```
+
+The key (e.g. `:audit_log`) must match a database key in `config/database.yml`. All reads and writes on `AuditLogEntry` — including `batch_audit` inserts and `WriteAuditLogJob` — use that connection automatically.
+
+### Test helpers
+
+**`RailsAuditLog::TestHelpers`** — silences audit tracking inside a block; useful in FactoryBot factories and seed data:
+
+```ruby
+# spec/rails_helper.rb
 require "rails_audit_log/test_helpers"
 
 RSpec.configure do |config|
   config.include RailsAuditLog::TestHelpers
 end
+```
 
-# Or include directly in FactoryBot definitions:
-FactoryBot.define do
-  factory :post do
-    after(:create) { |p| without_audit_log { p.update!(cached_at: Time.current) } }
-  end
-end
+```ruby
+# Or in a FactoryBot factory:
+after(:create) { |p| without_audit_log { p.update!(cached_at: Time.current) } }
 ```
 
 `without_audit_log` is a prefix-free wrapper around `RailsAuditLog.disable` — thread-safe and restores tracking even if the block raises.
 
-### Minitest assertions
+**`RailsAuditLog::Matchers`** (RSpec) — add to `spec/rails_helper.rb`:
 
-Add to your `test/test_helper.rb`:
+```ruby
+require "rails_audit_log/matchers"
+
+RSpec.configure do |config|
+  config.include RailsAuditLog::Matchers
+end
+```
+
+```ruby
+expect(post).to have_audit_log_entry
+expect(post).to have_audit_log_entry(:update)
+expect(post).to have_audit_log_entry(:update).touching(:title)
+
+expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update).touching(:title)
+```
+
+**`RailsAuditLog::MinitestAssertions`** — add to `test/test_helper.rb`:
 
 ```ruby
 require "rails_audit_log/minitest_assertions"
@@ -436,51 +582,182 @@ class ActiveSupport::TestCase
 end
 ```
 
-Then use the assertions in any test:
-
 ```ruby
-assert_audit_log_entry post                                      # any entry
-assert_audit_log_entry post, event: :update                      # update entry
-assert_audit_log_entry post, event: :update, touching: :title    # touching title
-refute_audit_log_entry post, event: :update                      # no update entry
-assert_audit_log_entry post, event: :update, message: "custom"  # custom failure message
+assert_audit_log_entry post, event: :update, touching: :title
+refute_audit_log_entry post, event: :destroy
+```
+
+## Stability and versioning
+
+[↑ Table of contents](#table-of-contents)
+
+`rails_audit_log` follows [Semantic Versioning](https://semver.org/) from 1.0.0. The public API is everything documented in this README. Anything not listed here is internal and may change between minor versions.
+
+| Version bump | Meaning |
+|---|---|
+| **Patch** (1.0.x) | Bug fixes only — no API changes |
+| **Minor** (1.x.0) | New features, backward-compatible |
+| **Major** (x.0.0) | Breaking changes with a documented migration path |
+
+### Public API surface
+
+**Module-level** — `RailsAuditLog`
+
+| Method / accessor | Purpose |
+|---|---|
+| `.configure { \|config\| }` | Block-style configuration |
+| `.with_actor(actor) { }` | Set whodunnit context for a block |
+| `.disable { }` | Suppress all audit writes for a block |
+| `.enabled?` | Whether audit writes are active |
+| `.audit_log_reason(value) { }` | Attach a free-text reason for a block |
+| `.batch_audit { }` | Buffer writes and flush with a single `insert_all!` |
+| `.version_at(record, time)` | Reconstruct record state at a point in time |
+| `.authenticate { }` | Gate web dashboard access |
+| `.ignored_attributes=` | Global columns excluded from all models |
+| `.store_snapshot=` | Store full object snapshot alongside diffs |
+| `.capture_request_metadata=` | Capture `remote_ip` and `user_agent` |
+| `.version_limit=` | Global entry cap per record |
+| `.async=` | Write audit entries via `WriteAuditLogJob` |
+| `.connects_to=` | Route `AuditLogEntry` to a separate database |
+| `.page_size=` | Entries per page in the web dashboard |
+| `.whodunnit_display=` | Proc for actor display name snapshot |
+| `.retention_period=` | Global time-based TTL for audit entries |
+
+**Concerns**
+
+| Class | Include in | Key methods |
+|---|---|---|
+| `RailsAuditLog::Auditable` | ActiveRecord models | `audit_log(only:, ignore:, meta:, associations:, version_limit:, retain_for:, async:)`, `skip_audit_log { }` |
+| `RailsAuditLog::Controller` | ActionController | `audit_log_actor { }` |
+
+**Model — `RailsAuditLog::AuditLogEntry`**
+
+Scopes: `created_events`, `updated_events`, `destroyed_events`, `by_actor`, `for_resource`, `since`, `until`, `touching`, `slim`, `for_period`
+
+Instance methods: `reify`, `previous`, `next`, `diff`, `changed_attributes`, `actor`
+
+Constants: `EVENTS`, `BLOB_COLUMNS`, `PERIODS`
+
+**Testing helpers**
+
+| Module | Require | Usage |
+|---|---|---|
+| `RailsAuditLog::Matchers` | `require "rails_audit_log/matchers"` | RSpec: `have_audit_log_entry`, `create_audit_log_entry` |
+| `RailsAuditLog::MinitestAssertions` | `require "rails_audit_log/minitest_assertions"` | Minitest: `assert_audit_log_entry`, `refute_audit_log_entry` |
+| `RailsAuditLog::TestHelpers` | `require "rails_audit_log/test_helpers"` | `without_audit_log { }` |
+
+**Jobs** (configure via ActiveJob)
+
+`RailsAuditLog::WriteAuditLogJob` — do not instantiate directly; enqueued when `async: true` is set.
+
+`RailsAuditLog::PruneAuditLogJob` — enqueue on a schedule to prune all audited models; also invoked by `bin/rails rails_audit_log:prune`.
+
+**Generators**
+
+`rails generate rails_audit_log:install` · `rails generate rails_audit_log:initializer`
+
+---
+
+## Migrating from PaperTrail
+
+[↑ Table of contents](#table-of-contents)
+
+Run the migration generator to produce a timestamped data migration:
+
+```bash
+bin/rails generate rails_audit_log:migrate_from_paper_trail
+bin/rails db:migrate
 ```
 
-### RSpec matchers
+The generated migration reads every row from PaperTrail's `versions` table and inserts it into `audit_log_entries`.
+
+### Column mapping
+
+| PaperTrail `versions` | `audit_log_entries` | Notes |
+|---|---|---|
+| `item_type` | `item_type` | Direct copy |
+| `item_id` | `item_id` | Direct copy |
+| `event` | `event` | `create` / `update` / `destroy` only; other values are skipped |
+| `object_changes` | `object_changes` | YAML or JSON → JSON (see below) |
+| `object` | `object` | YAML or JSON → JSON (see below) |
+| `whodunnit` | `whodunnit_snapshot` | PaperTrail stores actor as a plain string |
+| `created_at` | `created_at` | Direct copy |
+| — | `actor_type` / `actor_id` | **Not populated** — cannot be inferred from a string `whodunnit` |
+
+### YAML and JSON serialization
+
+PaperTrail serializes `object` and `object_changes` as **YAML** by default and as **JSON** when `PaperTrail.serializer = PaperTrail::Serializers::JSON` is configured. The migration handles both transparently — it tries JSON first, then falls back to YAML (with a permissive class list for the Ruby types PaperTrail commonly serializes).
+
+### Compatibility shim for gradual migration
 
-Add to your `spec/rails_helper.rb` (or `spec_helper.rb`):
+If you need your codebase to keep using PaperTrail's API while migrating, include `RailsAuditLog::PaperTrailCompat` alongside `Auditable`:
 
 ```ruby
-require "rails_audit_log/matchers"
+require "rails_audit_log/paper_trail_compat"
 
-RSpec.configure do |config|
-  config.include RailsAuditLog::Matchers
+class Article < ApplicationRecord
+  include RailsAuditLog::Auditable
+  include RailsAuditLog::PaperTrailCompat
 end
 ```
 
-Then use the matchers in any spec:
+This adds the familiar PaperTrail surface:
 
 ```ruby
-# Assert a record has a matching audit entry
-expect(post).to have_audit_log_entry
-expect(post).to have_audit_log_entry(:update)
-expect(post).to have_audit_log_entry(:update).touching(:title)
-
-# Assert a block creates a matching audit entry
-expect { post.update!(title: "New") }.to create_audit_log_entry
-expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update)
-expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update).touching(:title)
+article.versions                          # audit_log_entries ordered oldest-first
+article.paper_trail.version               # most recent AuditLogEntry
+article.paper_trail.previous_version      # reconstructed previous state (reify)
+article.paper_trail.originator            # whodunnit_snapshot string
+article.paper_trail.version_at(1.week.ago) # reconstructed state at a point in time
 ```
 
+`AuditLogEntry#reify` already matches PaperTrail's `Version#reify` — no additional alias needed.
+
+### What is not migrated
+
+- `versions` rows with an `event` value outside `create`, `update`, `destroy` (custom events added by some apps)
+- `actor_type` and `actor_id` — PaperTrail's `whodunnit` is a plain string and does not identify the actor model
+
+---
+
+## Companion gems
+
+[↑ Table of contents](#table-of-contents)
+
+> Coming in the 1.x series
+
+| Gem | What it adds |
+|---|---|
+| `rails_audit_log-graphql` | Mountable GraphQL endpoint at `/audit/graphql` — queryable audit trail for API-first apps without forcing `graphql-ruby` on users who don't need it |
+
+Each companion gem declares `rails_audit_log` as a dependency so you only add what you use.
+
 ## Requirements
 
+[↑ Table of contents](#table-of-contents)
+
 - Ruby >= 3.3
 - Rails >= 7.2
 
+## Performance
+
+[↑ Table of contents](#table-of-contents)
+
+See [BENCHMARKS.md](BENCHMARKS.md) for write throughput, `batch_audit` gains, query performance, storage efficiency, and notes on comparing against PaperTrail. To run the suite locally:
+
+```bash
+bundle exec rake dev:setup
+bundle exec rake benchmark
+```
+
 ## Contributing
 
+[↑ Table of contents](#table-of-contents)
+
 Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/rails_audit_log).
 
 ## License
 
+[↑ Table of contents](#table-of-contents)
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -16,6 +16,11 @@ end
 
 task default: ["bundle:audit:update", "bundle:audit:check", :rubocop, :zeitwerk, :spec]
 
+desc "Run the performance benchmark suite (requires dev:setup first)"
+task :benchmark do
+  sh "bundle exec ruby benchmarks/suite.rb"
+end
+
 # Development database tasks (operate on spec/dummy)
 namespace :dev do
   dummy_env = { "RAILS_ENV" => "development" }

data/app/concerns/rails_audit_log/auditable.rb

@@ -1,4 +1,24 @@
 module RailsAuditLog
+  # Include in any ActiveRecord model to automatically track +create+, +update+,
+  # and +destroy+ events as {AuditLogEntry} records.
+  #
+  # == Basic usage
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #   end
+  #
+  # == Configuring tracking
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #     audit_log only: %i[title body],
+  #               meta: { tenant_id: -> { Current.tenant_id } },
+  #               version_limit: 50,
+  #               async: true
+  #   end
+  #
+  # Adds a polymorphic +has_many :audit_log_entries+ association to the model.
   module Auditable
     extend ActiveSupport::Concern
 
@@ -8,10 +28,13 @@ module RailsAuditLog
       class_attribute :_audit_log_meta,           default: nil
       class_attribute :_audit_log_associations,   default: nil
       class_attribute :_audit_log_version_limit,  default: nil
+      class_attribute :_audit_log_retain_for,     default: nil
       class_attribute :_audit_log_async,          default: false
 
       _warn_if_audit_table_missing
 
+      # All {AuditLogEntry} records for this object, newest first by default.
+      # Destroyed when the object is destroyed.
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
                as: :item,
@@ -54,6 +77,7 @@ module RailsAuditLog
     end
 
     class_methods do
+      # @api private
       def _warn_if_audit_table_missing
         return if connection.table_exists?("audit_log_entries")
 
@@ -66,16 +90,55 @@ module RailsAuditLog
         # DB not reachable during this phase (e.g. before db:create) — skip the check
       end
 
-      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, async: nil)
+      # Configures auditing options for this model. Call once in the class body
+      # after +include RailsAuditLog::Auditable+.
+      #
+      # @param only [Array<Symbol>, nil] whitelist of attributes to track;
+      #   when set, all other attributes are ignored regardless of +ignore:+
+      # @param ignore [Array<Symbol>, nil] additional attributes to exclude on
+      #   top of {RailsAuditLog.ignored_attributes}; ignored when +only:+ is set
+      # @param meta [Hash{Symbol => Proc}, nil] per-entry metadata; each value
+      #   is a lambda called at write time — zero-argument lambdas receive no
+      #   arguments, one-argument lambdas receive the record instance
+      # @param associations [Boolean, Array<Symbol>, nil] when +true+, tracks
+      #   all +has_many+ and +has_and_belongs_to_many+ associations; pass an
+      #   array of association names to track only specific ones
+      # @param version_limit [Integer, nil] maximum number of entries to retain
+      #   per record; oldest entries are pruned after each write; overrides
+      #   {RailsAuditLog.version_limit} for this model
+      # @param retain_for [ActiveSupport::Duration, nil] per-model time-based TTL;
+      #   entries older than this duration are pruned after each write; overrides
+      #   {RailsAuditLog.retention_period} for this model
+      # @param async [Boolean, nil] when +true+, writes are dispatched via
+      #   +WriteAuditLogJob+; overrides {RailsAuditLog.async} for this model
+      # @return [void]
+      # @example
+      #   class Article < ApplicationRecord
+      #     include RailsAuditLog::Auditable
+      #     audit_log only: %i[title body published_at],
+      #               meta: { tenant_id: -> { Current.tenant_id } },
+      #               associations: %i[tags],
+      #               version_limit: 100,
+      #               retain_for: 30.days
+      #   end
+      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, retain_for: nil, async: nil)
         self._audit_log_only          = only.map(&:to_s)   if only
         self._audit_log_ignore        = ignore.map(&:to_s) if ignore
         self._audit_log_meta          = meta                if meta
         self._audit_log_associations  = associations        unless associations.nil?
         self._audit_log_version_limit = version_limit       unless version_limit.nil?
+        self._audit_log_retain_for    = retain_for          unless retain_for.nil?
         self._audit_log_async         = async               unless async.nil?
       end
     end
 
+    # Executes the block with audit logging disabled for this record's writes.
+    # A convenience wrapper around {RailsAuditLog.disable}.
+    #
+    # @yield executes the block without recording any audit entries
+    # @return [Object] the return value of the block
+    # @example Skip auditing during a bulk update
+    #   post.skip_audit_log { post.update!(cached_at: Time.current) }
     def skip_audit_log
       RailsAuditLog.disable { yield }
     end
@@ -142,8 +205,9 @@ module RailsAuditLog
       if (buffer = RailsAuditLog.batch_audit_buffer)
         buffer << entry_attrs.stringify_keys.merge("created_at" => Time.current)
       elsif _audit_log_async || RailsAuditLog.async
-        limit = self.class._audit_log_version_limit || RailsAuditLog.version_limit
-        WriteAuditLogJob.perform_later(entry_attrs.stringify_keys, version_limit: limit)
+        limit  = self.class._audit_log_version_limit || RailsAuditLog.version_limit
+        period = self.class._audit_log_retain_for || RailsAuditLog.retention_period
+        WriteAuditLogJob.perform_later(entry_attrs.stringify_keys, version_limit: limit, retention_period: period)
       else
         RailsAuditLog::AuditLogEntry.create!(entry_attrs)
         prune_audit_entries
@@ -151,14 +215,19 @@ module RailsAuditLog
     end
 
     def prune_audit_entries
-      limit = self.class._audit_log_version_limit || RailsAuditLog.version_limit
-      return unless limit
+      limit  = self.class._audit_log_version_limit || RailsAuditLog.version_limit
+      period = self.class._audit_log_retain_for || RailsAuditLog.retention_period
+      return unless limit || period
 
-      count = audit_log_entries.count
-      excess = count - limit
-      return unless excess > 0
+      if period
+        audit_log_entries.where(created_at: ..period.ago).delete_all
+      end
 
-      audit_log_entries.order(id: :asc).limit(excess).delete_all
+      if limit
+        count  = audit_log_entries.count
+        excess = count - limit
+        audit_log_entries.order(id: :asc).limit(excess).delete_all if excess > 0
+      end
     end
 
     def build_audit_metadata