Documentation
¶
Overview ¶
Package audit provides a unified audit trail for all agent activity.
Index ¶
- Constants
- func ParseFilterList(values ...string) []string
- type BufferedEmitter
- type Emitter
- type Event
- type ListOpts
- type ListResult
- type NopEmitter
- type SQLiteStore
- func (s *SQLiteStore) Close() error
- func (s *SQLiteStore) Insert(ctx context.Context, event Event) error
- func (s *SQLiteStore) InsertBatch(ctx context.Context, events []Event) error
- func (s *SQLiteStore) List(ctx context.Context, opts ListOpts) ([]Event, int, error)
- func (s *SQLiteStore) PruneBefore(ctx context.Context, before time.Time) (int, error)
- func (s *SQLiteStore) Stats(ctx context.Context, opts StatsOpts) (*Stats, error)
- type Stats
- type StatsOpts
- type Store
Constants ¶
const ( CategoryToolCall = "tool_call" CategorySkill = "skill" CategoryChannel = "channel" CategoryApproval = "approval" CategorySchedule = "schedule" CategoryLLM = "llm" CategoryConfig = "config" CategorySession = "session" CategoryMCP = "mcp" CategorySafety = "safety" CategorySupervisor = "supervisor" // CategoryEval covers eval and dry-run lifecycle events (a preview was // run, a run started/finished). The per-round events those turns produce // keep their ordinary categories (llm, tool_call) and are told apart by // their source, not by this category. CategoryEval = "eval" )
Event categories.
const ( StatusOK = "ok" StatusError = "error" StatusPending = "pending" StatusDenied = "denied" )
Event statuses.
Variables ¶
This section is empty.
Functions ¶
func ParseFilterList ¶ added in v0.43.0
ParseFilterList normalizes multi-valued filter input into the union form ListOpts.Categories / ListOpts.Statuses expect. Each input may itself be comma-separated, so both `?category=llm,tool_call` and the repeated `?category=llm&category=tool_call` spelling arrive here as the same set. Blanks are dropped and duplicates collapsed, so a lone "" (the dashboard's "All" chip) yields nil — i.e. no filter.
Types ¶
type BufferedEmitter ¶
type BufferedEmitter struct {
// contains filtered or unexported fields
}
BufferedEmitter accepts events via a channel and writes them in batches.
func NewBufferedEmitter ¶
func NewBufferedEmitter(store Store, bufSize int, logger *slog.Logger) *BufferedEmitter
NewBufferedEmitter creates a buffered emitter with the given buffer capacity.
func (*BufferedEmitter) Close ¶
func (e *BufferedEmitter) Close()
Close stops the flush loop and drains remaining events.
func (*BufferedEmitter) Emit ¶
func (e *BufferedEmitter) Emit(_ context.Context, event Event)
Emit queues an event for persistence. Non-blocking; drops events if buffer is full.
func (*BufferedEmitter) Flush ¶ added in v0.28.0
func (e *BufferedEmitter) Flush()
Flush synchronously drains all buffered events and writes them to the store. The emitter remains usable after Flush returns. Safe for concurrent use. Guarantees: all events emitted before Flush is called will be persisted when Flush returns. Events emitted concurrently during Flush may or may not be included.
func (*BufferedEmitter) Start ¶
func (e *BufferedEmitter) Start(ctx context.Context)
Start begins the background flush loop. Call Close to stop.
type Emitter ¶
Emitter is the interface for emitting audit events. Implementations must be safe for concurrent use.
type Event ¶
type Event struct {
ID int64 `json:"id"`
Timestamp time.Time `json:"timestamp"`
Category string `json:"category"`
Action string `json:"action"`
Agent string `json:"agent"`
Summary string `json:"summary"`
Detail string `json:"detail"`
Status string `json:"status"`
DurationMs int64 `json:"duration_ms"`
Source string `json:"source"`
ConversationID string `json:"conversation_id"`
}
Event represents a single audit log entry.
type ListOpts ¶
type ListOpts struct {
Categories []string
Agent string
Statuses []string
Source string
// ExcludeSources drops events carrying any of these sources. It is the
// negative counterpart of Source: filtering *to* a source was always
// possible, filtering one *out* was not — which matters because dry-run and
// eval turns emit under the ordinary llm/tool_call categories and would
// otherwise flood an unfiltered stream.
ExcludeSources []string
Search string
Since *time.Time
Until *time.Time
Limit int
Offset int
}
ListOpts controls filtering and pagination for audit event queries.
Categories and Statuses are unions: an event matches when it carries any one of the listed values. Empty (or nil) means "no filter on this field".
type ListResult ¶
type ListResult struct {
Events []Event `json:"events"`
Total int `json:"total"`
Limit int `json:"limit"`
Offset int `json:"offset"`
}
ListResult wraps a paginated list response.
type SQLiteStore ¶
type SQLiteStore struct {
// contains filtered or unexported fields
}
SQLiteStore implements Store using SQLite.
func NewInMemoryStore ¶
func NewInMemoryStore() (*SQLiteStore, error)
NewInMemoryStore creates an in-memory audit store (for testing).
func NewSQLiteStore ¶
func NewSQLiteStore(dbPath string) (*SQLiteStore, error)
NewSQLiteStore opens (or creates) the audit database at dbPath.
func (*SQLiteStore) Close ¶
func (s *SQLiteStore) Close() error
Close closes the database connection.
func (*SQLiteStore) Insert ¶
func (s *SQLiteStore) Insert(ctx context.Context, event Event) error
Insert persists a single audit event.
func (*SQLiteStore) InsertBatch ¶
func (s *SQLiteStore) InsertBatch(ctx context.Context, events []Event) error
InsertBatch persists multiple audit events in a single transaction.
func (*SQLiteStore) PruneBefore ¶
PruneBefore deletes audit events older than the given time. Returns the number of deleted rows.
type Stats ¶
type Stats struct {
Total int `json:"total"`
ByCategory map[string]int `json:"by_category"`
ByStatus map[string]int `json:"by_status"`
EventsLastHour int `json:"events_last_hour"`
}
Stats holds aggregate counts for the audit log dashboard.
type StatsOpts ¶ added in v0.43.0
StatsOpts controls filtering for aggregate audit queries. Stats needs the same source exclusion as List: eval and dry-run events land under existing categories, so without it one preview visibly inflates the dashboard's headline counts.
type Store ¶
type Store interface {
Insert(ctx context.Context, event Event) error
InsertBatch(ctx context.Context, events []Event) error
List(ctx context.Context, opts ListOpts) ([]Event, int, error)
Stats(ctx context.Context, opts StatsOpts) (*Stats, error)
PruneBefore(ctx context.Context, before time.Time) (int, error)
Close() error
}
Store persists and queries audit events.