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

Three paths

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

Quick start (recommended)

For a single business Ecto.Multi with one audit step — the common case:

Fort.Audit.audited_transaction(multi, "user.created",
  actor_id: actor.id,
  actor_type: "admin_user",
  audit_attrs: %{subject_id: user.id, subject_type: "user"}
)

Actor identity (actor_id, actor_type) and action are stated exactly once. The audit step is constructed correctly inside — MissingAuditStepError is structurally unreachable through this entry point.

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}
})

Advanced: multiple audit steps in one Multi

When you need more than one audit step inside a single transaction, use wrap/1, append_to_multi/3, and transact/4 directly.

Wrapping a Multi (existing or new)

Build a plain Ecto.Multi first, then wrap it — same path whether starting from scratch or wrapping an already-assembled 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)

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).