AuditLog (AuditLog v0.3.0)

Writes explicit semantic audit events through an Ecto repository.

The caller owns the transaction that makes a domain write atomic with its event. This module neither starts a hidden transaction nor stores implicit actor context.

Build an AuditLog.Actor, AuditLog.Context, and AuditLog.Subject, then call record/5 or record!/5. See the project README for a complete transaction example.

Summary

Functions

record(repo, action, context, subject, opts \\ [])

Records an event and returns the repository's insert/2 result.

record!(repo, action, context, subject, opts \\ [])

Records an event and returns it.

Functions

record(repo, action, context, subject, opts \\ [])

@spec record(
  module(),
  String.t(),
  AuditLog.Context.t(),
  AuditLog.Subject.t(),
  keyword()
) ::
  {:ok, AuditLog.Event.t()}
  | {:error, Ecto.Changeset.t() | AuditLog.InvalidValueError.t()}

Records an event and returns the repository's insert/2 result.

action must be a non-blank string without surrounding whitespace. Event metadata shallowly overrides context metadata on duplicate keys.

Options

:id - caller-supplied event UUID; generated by Ecto when omitted
:reason - optional prose; blank strings become nil
:metadata - JSON-object map canonicalized and merged over context metadata
:prefix - PostgreSQL schema prefix for the insert
:repo_opts - keyword list containing :timeout, :log, or :telemetry_options

Boundary errors return {:error, %AuditLog.InvalidValueError{}}. Event validation and declared database constraints return an Ecto changeset. Returned metadata uses string keys and JSON primitive values.

record!(repo, action, context, subject, opts \\ [])

@spec record!(
  module(),
  String.t(),
  AuditLog.Context.t(),
  AuditLog.Subject.t(),
  keyword()
) ::
  AuditLog.Event.t()

Records an event and returns it.

Accepts the same options as record/5. Boundary errors raise AuditLog.InvalidValueError. Validation and database errors raise the repository's normal Ecto exception.