This page complements Audit logging with implementation-level vocabulary used in library code and tests.
Primitives
Sigra.Audit.log/2— Inserts one row in its own transaction. Emits[:sigra, :audit, :log]on success only.Sigra.Audit.log_multi/3— Appends an audit step to an existingEcto.Multi. The caller runsRepo.transaction/1and must callSigra.Audit.emit_telemetry_from_changes/1in the success branch so telemetry never fires on rollback.Sigra.Audit.log_safe/3— Same shape aslog/2but no-ops whenaudit_schemais not configured. Used inside optional code paths so hosts without audit tables do not crash.
Atomicity (C-1 / SEED-002)
Where a business operation and its audit row must commit together, prefer Ecto.Multi + log_multi/3 + __log_internal__/3 (or log_multi_safe/3 where provided) inside a single transaction.
Sigra historically shipped a hybrid: a few hot paths use Ecto.Multi, while others still call log_safe/3 after the fact. Converting remaining sites is tracked as SEED-002; v1.3 proves the pattern on the API token create path in Sigra.APIToken with Postgres-backed tests.
C-1 matrix (post–v1.4 inventories): the authoritative “which boundary is T1 vs intentional T2 (EX-*)” table lives in 09-VERIFICATION.md (tag snapshot) — keep that file aligned with 43- / 44- / 45- AUD-04 inventories when audit mechanics change.
Testing
Sigra.Audit.Assertions— Plain functions for ordering-safe assertions against a real repo (seeguides/recipes/testing.md).Sigra.Testing.assert_audit_event/2— Convenience wrapper for ExUnit hosts.
Non-goals
- This document does not list every built-in action string; search
lib/sigra/forSigra.Auditcall sites. - OAuth ceremony audit rows are not guaranteed to have dedicated example-app smoke in every milestone; check release notes when upgrading.