Audit Trail

• Capture & storage — built into the agent. It instruments every collection through the collection hooks (so it is datasource-agnostic: SQL, Sequelize, Mongo, ActiveRecord, Mongoid…) and writes one row per changed record into a SQL database you provide.
• The History tab — in Forest, on each record’s detail page. It lists the record’s activity logs and enriches each one with the field-level diff captured by your agent.

​

Enable it on your agent

import { createAgent } from '@forestadmin/agent';

const agent = createAgent({
  // ...your usual options...
  auditTrail: {
    connectionString: process.env.AUDIT_TRAIL_DATABASE_URL,
  },
});

const agent = createAgent({
  // ...your usual options...
  auditTrail: process.env.AUDIT_TRAIL_DATABASE_URL
    ? { connectionString: process.env.AUDIT_TRAIL_DATABASE_URL }
    : null,
});

# config/initializers/forest_admin_rails.rb
ForestAdminRails.configure do |config|
  config.auth_secret = ENV['FOREST_AUTH_SECRET']
  config.env_secret  = ENV['FOREST_ENV_SECRET']

  config.audit_trail = { database: ENV['AUDIT_TRAIL_DATABASE_URL'] }
end

config.audit_trail = {
  database: {
    adapter: 'postgresql', host: ENV['AUDIT_DB_HOST'], port: ENV['AUDIT_DB_PORT'],
    username: ENV['AUDIT_DB_USER'], password: ENV['AUDIT_DB_PASSWORD'],
    database: ENV['AUDIT_DB_NAME']
  }
}

ForestAdminAgent::Builder::AgentFactory.instance.setup(
  auth_secret: ENV['FOREST_AUTH_SECRET'],
  env_secret: ENV['FOREST_ENV_SECRET'],
  # ...usual options...
  audit_trail: { database: ENV['AUDIT_TRAIL_DATABASE_URL'] }
)

​

Masking sensitive fields

auditTrail: {
  connectionString: process.env.AUDIT_TRAIL_DATABASE_URL,
  redact: { users: ['ssn', 'password'] },
}

config.audit_trail = {
  database: ENV['AUDIT_TRAIL_DATABASE_URL'],
  redact: { 'users' => %w[ssn password] }
}

​

What gets stored

​

Write protocol

• critical: false (default) — a failure recording the pending row is logged and swallowed; the write proceeds exactly as it would without the audit trail, just without an entry for it.
• critical: true — the same failure instead refuses the write: nothing happens, no compensating action is taken.

​

Correlation with activity logs

​

Smart actions

​

The History tab

• An entry with audit data renders as a card with field-level diffs and an operation badge — Created, Updated, Deleted, Action or Action failed.
• An entry without it (an older log, or an agent with no audit trail configured) falls back to a plain activity card.
• Action entries show the submitted form values rather than a before/after diff — a failed action changed nothing, so showing its inputs as an “after” state would be a lie.
• The filter panel narrows by author and date range, offers free-text search across the recorded values, and the sort toggle switches between newest-first (default) and oldest-first. All are applied server-side, so they filter the whole history, not the current page.
• The author filter’s options are populated from meta.availableUsers — no separate request needed.

​

HTTP routes

​

Searching

• action_name
• user_first_name, user_last_name, user_email
• the keys and the scalar values of previous_values and new_values, at any depth — searching Lyon finds {"address":{"city":"Lyon"}}

​

Reconstructing a past state

​

Limitations

• Only writes going through Forest are audited. Changes made by your own code outside the Forest data layer, by another application, or directly in the database leave no trace. Audit trail coverage is not database-level coverage.
• A concurrent overwrite can stale previous_values. The hooks bracket a write as separate calls and the data layer exposes no lock (it spans SQL, Mongo, HTTP APIs), so two writes racing on the same record snapshot the same prior state. new_values is always exact and no row is ever lost — only the before image of an overlapping write can be stale. Exact before-images under concurrency need database triggers or CDC.
• A record-level scope only protects a record that still exists. A scope can’t be evaluated against a record that is gone, so once it is genuinely deleted, anyone with read permission on the collection can see that something happened to it, by whom and when — seeing what was deleted is much of the point of an audit trail. It stops short of the actual values, though: a create or delete row’s captured values are withheld if they themselves would have failed the caller’s scope, and an update row’s values (only a partial diff, which can’t be checked against a scope reliably) are withheld unconditionally in that situation.
• By default, a broken audit store doesn’t block a write. A failure recording the pending entry is logged and the write proceeds unaudited — set critical: true to refuse the write instead; see Write protocol.
• Auditing costs extra queries. Updates and deletes snapshot the record before writing, so each mutating request adds database round-trips.
• A bulk update or delete audits at most 1000 records per operation. Matching more logs a warning and audits only the first 1000, unless critical: true is set, in which case the whole operation is refused instead of running partially audited.
• A smart action’s selection is capped at the same 1000. Naming only a subset of a wider selection would misstate what the action covered, so instead of truncating, an over-cap run is recorded as one entry attached to no record (the same way a global or select-all run already is) — or refused before it runs when critical: true is set.
• On Node.js, a renamed record’s history doesn’t walk back past the rename. The agent files an update under the record’s new id when a writable primary key changes, but has no previous_record_id column to chain that update back to the old id. The Ruby agent does have one, so the same record shows a complete timeline there and a history beginning at the rename on Node.js, until this column is ported.