Documentation
¶
Overview ¶
Package audit provides a unified audit trail for all agent activity.
Index ¶
- Constants
- 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, since *time.Time) (*Stats, error)
- type Stats
- 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" )
Event categories.
const ( StatusOK = "ok" StatusError = "error" StatusPending = "pending" StatusDenied = "denied" )
Event statuses.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 {
Category string
Agent string
Status string
Source string
Search string
Since *time.Time
Until *time.Time
Limit int
Offset int
}
ListOpts controls filtering and pagination for audit event queries.
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 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, since *time.Time) (*Stats, error)
PruneBefore(ctx context.Context, before time.Time) (int, error)
Close() error
}
Store persists and queries audit events.
Source Files