Audit Trail

• Capture & storage — built into the agent. It instruments every collection that has a primary key 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. A collection without one is skipped — there is nothing to file its rows under, and Node.js logs a warning naming it.
• The Activity tab — in Forest, on each record’s detail page. It replaces the previous activity tab: 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 Activity 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, activity type 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.

​

Project Activity Logs page

• Who can open the page is the team’s Activity Logs setting, as before. The agent does not add a gate of its own.
• What it shows follows the rule in Who sees the recorded values: if you can read a collection and your team has no scope on it, you see its rows’ values here as on each record’s tab.
• A collection your team has a record-level scope on has no audit trail on this page, whatever the scope’s condition, even one every record passes. A scope can’t be evaluated across the whole timeline without reading every record it mentions. The collection’s activity logs still appear, without diffs, since activity logs are not filtered by roles or scopes, and each carries a Scoped tag saying why it has no audit trail. Each record’s audit trail stays available on its own Activity tab.
• The page needs an agent that serves the cross-collection route: Node.js from 1.110.4 and Ruby from 1.46.3. On an older agent, or one without the audit trail configured, the page shows the activity logs alone.

​

HTTP routes

​

The timeline route

• sort=timestamp walks oldest first; anything else walks newest first. Ties follow the row id in the same direction.
• before (newest first) or after (oldest first) is an inclusive ISO 8601 instant, and excludeIds lists the row ids already served at it, so rows sharing a timestamp are never skipped or repeated. The bound for the other direction is ignored. The bound and the date filter on the same side combine, and the tighter one wins.
• meta.cursor holds the next page’s { before | after, excludeIds }, and is null on the last page.
• meta.availableUsers is sent on the first page only, when neither before nor after is given.

​

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

​

Who sees the recorded values

• A delete row keeps its previous values, and a create row its new values, only if they pass your scope. An update row’s two sides are a partial diff, so each side is tested on its own values and kept only if it passes.
• A side that can’t answer your scope is withheld rather than guessed at: a scope on a read-only column (never captured), on a relation, or on a value stored redacted. A captured null never passes a negated condition such as status != 'private', as in the database.
• The primary key is filled from the row’s own id where the row doesn’t capture it. On an update’s previous side, a redacted primary key is not filled, since a writable key may have moved: that side is withheld from a scope on the key.
• An id freed and taken again has two lives. When a record is deleted, or its primary key moves, and another record takes the same id, being able to read the current record says nothing about the earlier one. The rows from before the id was taken go through the same test as a deleted record’s, even though a record you can read holds the id now.
• The record is read twice, before and after the audit rows are, and the values are withheld if either read found it gone. An id taken by a record you cannot read answers 404.
• Action rows are not tested. An action or action_failed row holds the form values submitted to the action and a result summary, not column values, so your scope has nothing to test. It is returned as recorded, even on a deleted record outside your scope.

​

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 protects a deleted record’s values, not the fact that it changed. Anyone who can read the collection sees that a deleted record was touched, by whom and when; the values are tested against their scope. See Who sees the recorded values, including the agent versions this needs.
• 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.
• A record whose primary key moved starts its history at the move. An update that changes a writable primary key is filed under the record’s new id, and the rows written before stay under the old one, which the record’s timeline no longer reads. Both agents behave this way. Following a record across the move is left out until there is a need for it; tell us if you have one.