Documentation
¶
Overview ¶
Package postgres provides PostgreSQL storage for audit logs.
Index ¶
- type Config
- type Store
- func (s *Store) Breakdown(ctx context.Context, filter audit.BreakdownFilter) ([]audit.BreakdownEntry, error)
- func (s *Store) Cleanup(ctx context.Context) error
- func (s *Store) Close() error
- func (s *Store) Count(ctx context.Context, filter audit.QueryFilter) (int, error)
- func (s *Store) Discovery(ctx context.Context, startTime, endTime *time.Time) (*audit.DiscoveryStats, error)
- func (s *Store) Distinct(ctx context.Context, column string, startTime, endTime *time.Time) ([]string, error)
- func (s *Store) DistinctPairs(ctx context.Context, col1, col2 string, startTime, endTime *time.Time) (map[string]string, error)
- func (s *Store) DropExpiredPartitions(ctx context.Context, retentionDays int) error
- func (s *Store) Enrichment(ctx context.Context, startTime, endTime *time.Time) (*audit.EnrichmentStats, error)
- func (s *Store) EnsureMonthlyPartitions(ctx context.Context, monthsAhead int) error
- func (s *Store) Log(ctx context.Context, event audit.Event) error
- func (s *Store) Overview(ctx context.Context, filter audit.MetricsFilter) (*audit.Overview, error)
- func (s *Store) Performance(ctx context.Context, filter audit.MetricsFilter) (*audit.PerformanceStats, error)
- func (s *Store) Query(ctx context.Context, filter audit.QueryFilter) ([]audit.Event, error)
- func (s *Store) StartCleanupRoutine(interval time.Duration)
- func (s *Store) Timeseries(ctx context.Context, filter audit.TimeseriesFilter) ([]audit.TimeseriesBucket, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
RetentionDays int
}
Config configures the PostgreSQL audit store.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements audit.Logger using PostgreSQL.
func (*Store) Breakdown ¶ added in v0.17.1
func (s *Store) Breakdown(ctx context.Context, filter audit.BreakdownFilter) ([]audit.BreakdownEntry, error)
Breakdown returns audit event counts grouped by a dimension.
func (*Store) Close ¶
Close cancels the cleanup goroutine and waits for it to exit. It is safe to call Close even if StartCleanupRoutine was never called.
func (*Store) Count ¶ added in v0.17.0
Count returns the number of audit events matching the filter.
func (*Store) Discovery ¶ added in v0.25.0
func (s *Store) Discovery(ctx context.Context, startTime, endTime *time.Time) (*audit.DiscoveryStats, error)
Discovery returns discovery-before-query pattern statistics for the given time range.
func (*Store) Distinct ¶ added in v0.17.1
func (s *Store) Distinct(ctx context.Context, column string, startTime, endTime *time.Time) ([]string, error)
Distinct returns sorted unique values for the given column, scoped by optional time range.
func (*Store) DistinctPairs ¶ added in v0.18.2
func (s *Store) DistinctPairs(ctx context.Context, col1, col2 string, startTime, endTime *time.Time) (map[string]string, error)
DistinctPairs returns a mapping of col1 values to col2 values. When col2 is empty for a row, the row is skipped. This is used to map e.g. user_id to user_email for display labels.
func (*Store) DropExpiredPartitions ¶ added in v1.67.0
DropExpiredPartitions removes named monthly partitions whose entire date range has aged past the retention window. The default partition (audit_logs_default) is never dropped; rows that landed there are removed by the row-level DELETE in Cleanup.
A partition is considered expired when its end date (the exclusive upper bound) is at or before the retention cutoff. For example, with retention=90 days and today=2026-09-30, partitions covering ranges ending on or before 2026-07-02 are dropped.
func (*Store) Enrichment ¶ added in v0.25.0
func (s *Store) Enrichment(ctx context.Context, startTime, endTime *time.Time) (*audit.EnrichmentStats, error)
Enrichment returns aggregate enrichment statistics for the given time range.
func (*Store) EnsureMonthlyPartitions ¶ added in v1.67.0
EnsureMonthlyPartitions creates named monthly partitions of audit_logs for the next monthsAhead months starting from next month. The current month is intentionally skipped so a brownfield deployment (where rows for the current month already exist in audit_logs_default) does not fail with "partition key conflicts with row in default partition". Existing rows in audit_logs_default age out through the standard retention DELETE; once the first named partition's window opens, new rows route into it automatically.
Safe to call repeatedly; CREATE TABLE IF NOT EXISTS makes each statement idempotent.
func (*Store) Overview ¶ added in v0.17.1
Overview returns aggregate statistics for the given filter.
func (*Store) Performance ¶ added in v0.17.1
func (s *Store) Performance(ctx context.Context, filter audit.MetricsFilter) (*audit.PerformanceStats, error)
Performance returns latency percentile statistics for the given filter.
func (*Store) StartCleanupRoutine ¶
StartCleanupRoutine starts a background goroutine that periodically deletes old audit logs, creates upcoming monthly partitions, and drops partitions whose entire date range has aged past the retention window. The goroutine is stopped when Close is called.
Partition rotation is best-effort: a failure to create or drop a partition is logged and skipped, never aborts the retention DELETE that runs on the same tick. This keeps audit_logs bounded even on a database where the partition operations have transient errors.
In multi-replica deployments, only one pod per tick acquires the audit maintenance advisory lock and runs the steps; the rest skip silently until the next tick. The initial pre-tick ensure also runs under the lock so simultaneous pod restarts do not stampede on CREATE TABLE.
func (*Store) Timeseries ¶ added in v0.17.1
func (s *Store) Timeseries(ctx context.Context, filter audit.TimeseriesFilter) ([]audit.TimeseriesBucket, error)
Timeseries returns audit event counts bucketed by the given resolution.
Source Files