audit

audit

import "github.com/altessa-s/go-atlas/data/audit"

Package audit provides high-performance, asynchronous user action auditing with at-least-once delivery semantics.

Auditor is a thin facade over a Dispatcher (typically dispatch.Engine). The caller creates and starts the dispatch engine, then passes it to New. Events flow through the engine's pipeline: channel buffer, worker pool, batch buffer, and storage write with exponential-backoff retry. Zero impact on request latency.

Key types

Type / Interface	Description
Auditor	Main entry point for emitting audit events (non-blocking)
Dispatcher	Async item dispatch interface (Submit, Dropped)
Storage	Persistence interface: Store, StoreBatch, Query, Count, Close
StorageSink	Adapts Storage to dispatch.Sink for engine construction
JSONCodec	Default dispatch.Codec for WAL durability (JSON)
Event	Single audit event with full context
EventType	Category: api.request, business.event, data.change, auth
Action	Operation: create, read, update, delete, execute, login, etc.
Actor	Entity performing an action (user, service, api_key, etc.)
Resource	Target of the action with optional change tracking
Result	Outcome with status, code, message, and error details
Query	Filter criteria for querying stored events

Options

Option	Default	Description
WithServiceInfo	--	Service identification (name, version)
WithLogger	discard	Structured logger (*slog.Logger)
WithCollector	noop	Prometheus metrics collector
WithMetricsSubsystem	"audit"	Override the metrics subsystem name

Dispatch-level options (buffer, batch, workers, retries, WAL) are configured on the dispatch.Engine — see service/dispatch.

Usage

storage := memory.New()
eng, _ := dispatch.NewEngine[*audit.Event](
    audit.StorageSink{Storage: storage},
    dispatch.WithBufferSize[*audit.Event](10000),
)
eng.Start()
defer eng.Shutdown(ctx)

auditor, _ := audit.New(eng,
    audit.WithServiceInfo(audit.ServiceInfo{Name: "my-service"}),
    audit.WithCollector(collector),
)
auditor.Start()
defer auditor.Shutdown(ctx)

// Fire-and-forget
auditor.Emit(&audit.Event{...})

// Fluent builder
auditor.NewEvent(audit.EventTypeDataChange, audit.ActionUpdate).
    WithResource(resource).
    WithSuccess().
    Emit()

Subpackages

Package	Description
factory	Fluent builder from config
storages/memory	In-memory backend for dev/test
storages/mongo	MongoDB-backed persistent storage