Audit configuration reference

echo.labstack.com/pro v0.2.0. See the task guide for setup examples.

Required fields

• SchemaConfig.Keys: HMAC keys for the default storage policy; Policy.AllowMaskFallback permits masking instead.
• MemoryStoreConfig.Capacity: positive event and byte capacities; a full store never evicts older events.
• auditpg: caller-owned pools, a NOLOGIN deployment owner and four distinct runtime roles (auditpg.Roles).

A reader pagination cursor does not grant access; authorize every read and continuation.

audit.SchemaConfig

Import echo.labstack.com/pro/audit.

audit.SchemaConfig · audit/schema.go:110 · echo.labstack.com/[email protected]

SchemaConfig contains copied field registrations and projection policy.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Fields	map[string]redact.Class	Fields is copied; nil registers no metadata fields. At most 256 names matching [a-z][a-z0-9_]{0,63} may be registered with valid classes.	Fields is copied; nil registers no metadata fields.	audit/schema.go:113
Policy	redact.StorePolicy	Policy sets how each field class is stored, such as masking or HMAC hashing. Construction copies its Modes map. The zero value selects redact defaults and requires HMAC Keys unless AllowMaskFallback is set.	The zero value selects redact defaults and requires HMAC Keys unless AllowMaskFallback is set.	audit/schema.go:117
Keys	*redact.Keyring	Keys is an immutable caller-owned keyring retained by Schema. Keep it usable independently of the Schema lifetime. Nil requires Policy.AllowMaskFallback when an HMAC mode is selected.	Nil requires Policy.AllowMaskFallback when an HMAC mode is selected.	audit/schema.go:121
Now	func() time.Time	Now is retained and must be concurrency safe; nil uses time.Now.	Now is retained and must be concurrency safe; nil uses time.Now.	audit/schema.go:123

Functions from package source

Type	Source
func NewSchema(c SchemaConfig) (*Schema, error)	audit/schema.go:138

audit.MemoryStoreConfig

Import echo.labstack.com/pro/audit.

audit.MemoryStoreConfig · audit/memory.go:48 · echo.labstack.com/[email protected]

MemoryStoreConfig bounds process-local recording. Capacity is copied.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Capacity	Capacity	Capacity requires positive event and byte bounds; there are no defaults.	Capacity requires positive event and byte bounds; there are no defaults.	audit/memory.go:51
Timeout	time.Duration	Timeout bounds lock waits, TestTransaction.Record, Commit and Rollback calls, and ReadView including its callback. It defaults to 5s; valid range 100ms–60s.	It defaults to 5s; valid range 100ms–60s.	audit/memory.go:54
Now	func() time.Time	Now is retained and must be concurrency safe; nil uses time.Now.	Now is retained and must be concurrency safe; nil uses time.Now.	audit/memory.go:56

Functions from package source

Type	Source
func NewMemoryStore(c MemoryStoreConfig) (*MemoryStore, error)	audit/memory.go:83

audit.Capacity

Import echo.labstack.com/pro/audit.

audit.Capacity · audit/memory.go:40 · echo.labstack.com/[email protected]

Capacity bounds event count and total serialized bytes, without eviction. Both bounds must be positive. Duplicate recordings consume no capacity.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Events	int	Events is required and must be positive; there is no default.	Events is required and must be positive; there is no default.	audit/memory.go:42
Bytes	int	Bytes is required and must be positive; there is no default.	Bytes is required and must be positive; there is no default.	audit/memory.go:44

audit.MiddlewareConfig

Import echo.labstack.com/pro/audit.

audit.MiddlewareConfig · audit/middleware.go:59 · echo.labstack.com/[email protected]

MiddlewareConfig maps requests to audit fields after routing and authentication. Callbacks must support concurrent calls. RealIP comes from deployment configuration. It is not a verified principal.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Actor	func(*echo.Context) (Actor, error)	Actor is required; it resolves the verified principal and must not retain c.	Actor is required; it resolves the verified principal and must not retain c.	audit/middleware.go:62
Tenant	func(*echo.Context) (string, error)	Tenant is optional; nil uses the global (empty) tenant. It must not retain c.	Tenant is optional; nil uses the global (empty) tenant.	audit/middleware.go:65
RequestIDHeader	string	RequestIDHeader defaults to X-Request-ID and must be a valid HTTP field name.	RequestIDHeader defaults to X-Request-ID and must be a valid HTTP field name.	audit/middleware.go:68

Functions from package source

Type	Source
func (cfg MiddlewareConfig) ToMiddleware() (echo.MiddlewareFunc, error)	audit/middleware.go:79

audit.DenialConfig

Import echo.labstack.com/pro/audit.

audit.DenialConfig · audit/denial.go:28 · echo.labstack.com/[email protected]

DenialConfig records denials only on routes or groups where installed. Install it first, outside route authentication and authorization. Recording is synchronous and fail-open by default. Callbacks must be concurrency safe and must not retain the Echo context. Logger remains caller-owned.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Schema	*Schema	Schema is required, constructed and caller-owned.	Schema is required, constructed and caller-owned.	audit/denial.go:30
Recorder	Recorder	Recorder is required, caller-owned and must honor its recording context.	Recorder is required, caller-owned and must honor its recording context.	audit/denial.go:33
Actor	func(*echo.Context) (Actor, error)	Actor is optional; nil or a failed callback uses Anonymous when no Scope exists.	Actor is optional; nil or a failed callback uses Anonymous when no Scope exists.	audit/denial.go:36
Tenant	func(*echo.Context) (string, error)	Tenant is optional; nil or a failed callback uses the global tenant when no Scope exists.	Tenant is optional; nil or a failed callback uses the global tenant when no Scope exists.	audit/denial.go:39
Statuses	[]int	Statuses lists 1–8 distinct 4xx statuses to record. It defaults to 401 and 403 and is copied.	It defaults to 401 and 403 and is copied.	audit/denial.go:42
Action	string	Action defaults to http.request.denied.	Action defaults to http.request.denied.	audit/denial.go:44
FailClosed	bool	FailClosed returns *DenialUnrecordedError if recording fails before the response is written. If false (the default), the client gets the original denial.	If false (the default), the client gets the original denial.	audit/denial.go:47
Timeout	time.Duration	Timeout defaults to 500ms; valid range 50ms–5s.	Timeout defaults to 500ms; valid range 50ms–5s.	audit/denial.go:49
MaxInFlight	int	MaxInFlight limits concurrent recording calls. Default 64; valid range 1–1024.	Default 64; valid range 1–1024.	audit/denial.go:51
RequestIDHeader	string	RequestIDHeader defaults to X-Request-ID.	RequestIDHeader defaults to X-Request-ID.	audit/denial.go:53
Logger	*slog.Logger	Logger is optional and receives only sanitized codes.	Logger is optional and receives only sanitized codes.	audit/denial.go:55

Functions from package source

Type	Source
func (cfg DenialConfig) ToMiddleware() (echo.MiddlewareFunc, error)	audit/denial.go:80

audit.ReaderConfig

Import echo.labstack.com/pro/audit.

audit.ReaderConfig · audit/read.go:139 · echo.labstack.com/[email protected]

ReaderConfig is copied by NewReader. Schema, Access and Now are caller-owned and must be concurrency safe. Query and Get ignore Access.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Schema	*Schema	Schema is required and retained; it must carry the recording keyring (non-nil Keys), including retained keys.	Schema is required and retained; it must carry the recording keyring (non-nil Keys), including retained keys.	audit/read.go:142
Access	Recorder	Access is required for Reveal and Export. Its record must commit on its own, outside the caller's transaction.	Access is required for Reveal and Export.	audit/read.go:145
TokenTTL	time.Duration	default 15m; 1m–24h	default 15m; 1m–24h.	audit/read.go:146
MaxExports	int	default 2; 1–16 concurrent snapshot exports per Reader	default 2; 1–16 concurrent snapshot exports per Reader.	audit/read.go:147
Now	func() time.Time	default time.Now; must not block	default time.Now; must not block.	audit/read.go:148

Functions from package source

Type	Source
func NewReader(b ReadBackend, c ReaderConfig) (*Reader, error)	audit/read.go:165

audit.RelayConfig

Import echo.labstack.com/pro/audit.

audit.RelayConfig · audit/relay.go:163 · echo.labstack.com/[email protected]

RelayConfig configures a delivery coordinator and is copied by NewRelay. Run owns one coordinator and one renewal worker.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Name	string	Name is required and identifies an already registered cursor: 1–64 ASCII lowercase letters, digits, underscores or hyphens, starting with a letter.	Name is required and identifies an already registered cursor: 1–64 ASCII lowercase letters, digits, underscores or hyphens, starting with a letter.	audit/relay.go:167
Exporter	Exporter	Exporter is required and retained; it must honor cancellation and declare the same representation as the registered cursor.	Exporter is required and retained; it must honor cancellation and declare the same representation as the registered cursor.	audit/relay.go:170
Witness	ProgressWitness	Witness, if set, durably records how far the relay has delivered. It is caller-owned. Nil disables the witness.	Nil disables the witness.	audit/relay.go:173
Batch	int	Batch defaults to 256 (1–4096); MaxBytes defaults to 1 MiB (64 KiB–8 MiB).	Batch defaults to 256 (1–4096); MaxBytes defaults to 1 MiB (64 KiB–8 MiB).	audit/relay.go:176
MaxBytes	int	Batch defaults to 256 (1–4096); MaxBytes defaults to 1 MiB (64 KiB–8 MiB).	Batch defaults to 256 (1–4096); MaxBytes defaults to 1 MiB (64 KiB–8 MiB).	audit/relay.go:176
Poll	time.Duration	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	audit/relay.go:179
Lease	time.Duration	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	audit/relay.go:179
Backoff	time.Duration	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	Poll defaults to 1s and must be positive. Lease defaults to 30s (5s–5m). Backoff defaults to 1s (1s–5m).	audit/relay.go:179
Logger	*slog.Logger	Logger is optional and caller-owned. Relay does not log yet; this field is reserved for future use.	Logger is optional and caller-owned.	audit/relay.go:182

Functions from package source

Type	Source
func NewRelay(b RelayBackend, c RelayConfig) (*Relay, error)	audit/relay.go:198

auditpg.Roles

Import echo.labstack.com/pro/audit/auditpg.

auditpg.Roles · audit/auditpg/store.go:50 · echo.labstack.com/[email protected]

Roles names the trusted NOLOGIN deployment owner and four independent runtime roles. Empty fields default to audit_deployment, audit_recorder, audit_relay, audit_maintenance and audit_reader. Roles must already exist; migration never creates logins. Use keyed literals: adding Reader breaks positional literals.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Deployment	string	Deployment defaults to audit_deployment.	Deployment defaults to audit_deployment.	audit/auditpg/store.go:52
Recorder	string	Recorder defaults to audit_recorder.	Recorder defaults to audit_recorder.	audit/auditpg/store.go:54
Relay	string	Relay defaults to audit_relay.	Relay defaults to audit_relay.	audit/auditpg/store.go:56
Maintenance	string	Maintenance defaults to audit_maintenance.	Maintenance defaults to audit_maintenance.	audit/auditpg/store.go:58
Reader	string	Reader defaults to audit_reader.	Reader defaults to audit_reader.	audit/auditpg/store.go:60

auditpg.SchemaConfig

Import echo.labstack.com/pro/audit/auditpg.

auditpg.SchemaConfig · audit/auditpg/store.go:66 · echo.labstack.com/[email protected]

SchemaConfig selects a schema, exact role grants and operation deadlines. An earlier caller deadline or cancellation still ends an operation first. Values are copied by New.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Schema	string	Schema defaults to public; use [A-Za-z_][A-Za-z0-9_]{0,62}.	Schema defaults to public; use [A-Za-z_][A-Za-z0-9_]{0,62}.	audit/auditpg/store.go:68
Roles	Roles	Roles selects existing deployment and runtime roles. Empty fields use Roles defaults; names must be distinct.	Empty fields use Roles defaults; names must be distinct.	audit/auditpg/store.go:71
Timeout	time.Duration	Timeout bounds ordinary operations; zero uses 5s, valid range 100ms–60s.	Timeout bounds ordinary operations; zero uses 5s, valid range 100ms–60s.	audit/auditpg/store.go:74
MigrateTimeout	time.Duration	MigrateTimeout bounds the whole migration in place of Timeout; zero uses 1m, valid range 1s–1h.	MigrateTimeout bounds the whole migration in place of Timeout; zero uses 1m, valid range 1s–1h.	audit/auditpg/store.go:77

Functions from package source

Type	Source
func New(ctx context.Context, pool *pgxpool.Pool, c SchemaConfig) (*Store, error)	audit/auditpg/store.go:323

auditadmin.PanelConfig

Import echo.labstack.com/pro/audit/auditadmin.

auditadmin.PanelConfig · audit/auditadmin/panel.go:22 · echo.labstack.com/[email protected]

PanelConfig configures the read-only Audit panel. Reveal additionally requires Principal.Reveal.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
ID	string	ID defaults to audit; use [a-z][a-z0-9-]{0,31}, excluding api and assets. When pointing the panel at a different store, change ID or the console Keys so old cursors stop working.	ID defaults to audit; use [a-z][a-z0-9-]{0,31}, excluding api and assets.	audit/auditadmin/panel.go:26
Reader	*audit.Reader	Reader is required, concurrency safe and caller-owned; it is never closed.	Reader is required, concurrency safe and caller-owned; it is never closed.	audit/auditadmin/panel.go:28
ActorClass	redact.Class	ActorClass defaults to Identifier; SensitiveDigest8 is also accepted.	ActorClass defaults to Identifier; SensitiveDigest8 is also accepted.	audit/auditadmin/panel.go:30
TargetClass	redact.Class	TargetClass defaults to Identifier; Public, SensitiveIP and SensitiveDigest8 are also accepted. A request's class parameter overrides this default.	TargetClass defaults to Identifier; Public, SensitiveIP and SensitiveDigest8 are also accepted. A request's class parameter overrides this default.	audit/auditadmin/panel.go:33
EnableReveal	bool	EnableReveal adds the privileged POST read that writes an audit record. Default false.	Default false.	audit/auditadmin/panel.go:35
PrincipalClass	redact.Class	PrincipalClass sets the class of the actor field in reveal audit records. It defaults to Identifier; SensitiveDigest8 is also accepted.	It defaults to Identifier; SensitiveDigest8 is also accepted.	audit/auditadmin/panel.go:38
RevealReasons	[]string	RevealReasons is copied; empty selects incident_response, customer_request and legal_request. Otherwise supply 1–16 distinct [a-z0-9_]{1,64} codes.	RevealReasons is copied; empty selects incident_response, customer_request and legal_request.	audit/auditadmin/panel.go:42

Functions from package source

Type	Source
func NewPanel(c PanelConfig) (*Panel, error)	audit/auditadmin/panel.go:56

Event and read limits

Setting	Default or limit
SchemaConfig.Fields	At most 256
Event.Action	Two to eight dot-separated segments, at most 128 bytes. The audit. prefix is reserved.
DenialConfig.Timeout / MaxInFlight	500 ms recording timeout and 64 concurrent calls by default
auditpg.SchemaConfig.Schema	public by default
auditpg.SchemaConfig.Timeout	Five seconds by default
auditpg.SchemaConfig.MigrateTimeout	One minute by default
QueryRequest.Limit	50 entries by default; at most 100

Keep pools and stores open until requests, relay work and retention work have stopped.

Related pages

Package explanation · Task guide · Problem catalog