Audit Sink (Compliance Trail)

The audit sink exposes the existing AuditTrail system as a standard plugin so you can turn on compliance logging with configuration instead of custom wiring.

Enable

from fapilog import Settings, get_logger

settings = Settings()
settings.core.sinks = ["audit"]
settings.sink_config.audit.storage_path = "./audit_logs"
settings.sink_config.audit.compliance_level = "soc2"

logger = get_logger(name="app", settings=settings)
logger.info("viewed record", user_id="u-123", contains_pii=True)

Configuration

sink_config.audit controls the sink:

  • compliance_level — basic, sox, hipaa, gdpr, pci_dss, soc2, iso27001

  • storage_path — directory for JSONL audit files

  • retention_days — retention window (metadata only; manage rotation/archival per policy)

  • require_integrity — keep hash-chain integrity fields for tamper detection

  • real_time_alerts — enable policy-driven alert detection (delivery requires custom integration; see Enterprise Features)

Event Mapping

  • Error/critical log levels map to ERROR_OCCURRED

  • Warning maps to COMPLIANCE_CHECK

  • All other levels map to DATA_ACCESS

  • Set audit_event_type in logger.* metadata to override per-entry

User/session context is lifted from log metadata when present (user_id, session_id, request_id, contains_pii, contains_phi).

Verification

Audit files include sequence numbers and hash-chain fields. Verify integrity at any time:

from pathlib import Path
from fapilog.core.audit import AuditTrail

trail = AuditTrail(storage_path=Path("./audit_logs"))
result = await trail.verify_chain_from_storage()
assert result.valid

Hash-chain integrity is preserved across sink start/stop; each write updates the chain and sequence numbers in order.