Atomic audit logging with dual routing: persists to PostgreSQL and emits structured JSON via :logger.

Two paths

• Transactional (transact/4) — audit row committed atomically with business steps inside an Ecto.Multi. Logger emission is secondary.
• Standalone (log/1) — single audit insert outside a Multi. Logger emission is synchronous with the DB write.

Configuration

config :fort_audit, :repo, MyApp.Repo
config :fort_audit, :logger_label_fields, [:outcome, :action]

:repo (required)

The Ecto repo used for all audit log persistence.

:logger_label_fields (optional)

Controls which metadata fields are emitted as top-level Logger metadata keys (indexed as labels by Loki Promtail, Datadog, Elasticsearch, etc.).

Default: [:outcome, :actor_type, :subject_type] — the three fields whose cardinality is bounded by design. All remaining fields (actor_id, subject_id, category, audit_log_id) nest under a single :details key to prevent accidental label-cardinality explosions.

See Fort.Audit.Emitter for the full rationale.

Usage

Existing Multi

Use wrap/1 to attach audit to an already-assembled Ecto.Multi:

Multi.new()
|> Multi.insert(:user, user_changeset)
|> Fort.Audit.wrap()
|> Fort.Audit.append_to_multi(:audit, %{
  actor_id: actor.id,
  actor_type: "admin_user",
  action: "user.created"
})
|> Fort.Audit.transact("user.created", actor.id)

Greenfield

Use new/0 when starting from scratch:

Fort.Audit.new()
|> then(fn %Fort.AuditedMulti{multi: multi} ->
  %{multi | multi: Multi.insert(multi, :org, org_changeset)}
end)
|> Fort.Audit.append_to_multi(:audit, %{
  actor_id: actor.id,
  actor_type: "admin_user",
  action: "org.created"
})
|> Fort.Audit.transact("org.created", actor.id)

Standalone

Use log/1 outside a transaction:

Fort.Audit.log(%{
  actor_id: actor.id,
  actor_type: "admin_user",
  action: "user.registration.rejected",
  outcome: "failure",
  metadata: %{reason: reason}
})

Logger metadata structure

Logger lines emitted by transact/4 and log/1 follow a two-tier metadata structure to prevent accidental label-cardinality explosions:

• Labels — top-level metadata keys (configured via :logger_label_fields, default [:outcome, :actor_type, :subject_type])
• Body — everything else nested under a single :details key (one JSON object, not N individual indexed fields)

See Fort.Audit.Emitter for full rationale and configuration.

Shipment to external systems

Fort's responsibility ends at emitting a well-structured Elixir Logger line. Getting logs into Loki, Elasticsearch, Datadog, or any other collector is the job of the host application's existing observability pipeline — Promtail, Vector, Fluent Bit, logger_json, or any Elixir Logger backend already in use. Fort does not ship a dedicated Loki/Elasticsearch/Datadog client for the same reason it does not ship a web framework adapter in the core library: those are integration concerns best solved by the community or the host app against stable Logger output.

Reconciliation

Rows that were persisted but never emitted to Logger (e.g., a crash between the DB commit and the emitted_at stamp) can be recovered via:

mix fort.reconcile

This queries unemitted rows using the partial index idx_audit_logs_unemitted, re-emits each via Logger, and stamps emitted_at. The function Fort.Audit.reconcile/2 is also public for host apps that want to schedule reconciliation from Oban, Quantum, or a :timer.send_interval.

At-least-once

Logger emission is at-least-once — a crash between the Logger call and the emitted_at DB stamp may cause re-emission on restart. Downstream consumers should dedupe on audit_logs.id for exactly-once processing. The mix fort.reconcile task is the recovery mechanism for the permanent case (crash before the stamp ever happens).