audit

package
v0.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package audit provides audit logging for the platform.

Index

Constants

This section is empty.

Variables

View Source 
var ValidBreakdownDimensions = map[BreakdownDimension]bool{
	BreakdownByToolName:    true,
	BreakdownByUserID:      true,
	BreakdownByPersona:     true,
	BreakdownByToolkitKind: true,
	BreakdownByConnection:  true,
}

ValidBreakdownDimensions is the set of allowed group-by values.

View Source 
var ValidResolutions = map[Resolution]bool{
	ResolutionMinute: true,
	ResolutionHour:   true,
	ResolutionDay:    true,
}

ValidResolutions is the set of allowed resolution values.

View Source 
var ValidSortColumns = map[string]bool{
	"timestamp":          true,
	"user_id":            true,
	"tool_name":          true,
	"toolkit_kind":       true,
	"connection":         true,
	"duration_ms":        true,
	"success":            true,
	"enrichment_applied": true,
}

ValidSortColumns lists columns that can be used for ORDER BY.

Functions

func SanitizeParameters 

func SanitizeParameters(params map[string]any) map[string]any

SanitizeParameters removes sensitive parameters from the event.

Types

type BreakdownDimension added in v0.17.1 

type BreakdownDimension string

BreakdownDimension defines valid group-by dimensions. 

const (
	// BreakdownByToolName groups by tool name.
	BreakdownByToolName BreakdownDimension = "tool_name"

	// BreakdownByUserID groups by user ID.
	BreakdownByUserID BreakdownDimension = "user_id"

	// BreakdownByPersona groups by persona.
	BreakdownByPersona BreakdownDimension = "persona"

	// BreakdownByToolkitKind groups by toolkit kind.
	BreakdownByToolkitKind BreakdownDimension = "toolkit_kind"

	// BreakdownByConnection groups by connection.
	BreakdownByConnection BreakdownDimension = "connection"
)

type BreakdownEntry added in v0.17.1 

type BreakdownEntry struct {
	Dimension     string  `json:"dimension"`
	Count         int     `json:"count"`
	SuccessRate   float64 `json:"success_rate"`
	AvgDurationMS float64 `json:"avg_duration_ms"`
}

BreakdownEntry holds aggregated stats for a single dimension value.

type BreakdownFilter added in v0.17.1 

type BreakdownFilter struct {
	GroupBy   BreakdownDimension
	Limit     int
	StartTime *time.Time
	EndTime   *time.Time
}

BreakdownFilter controls breakdown query parameters.

type Config 

type Config struct {
	Enabled       bool
	LogToolCalls  bool
	RetentionDays int
}

Config configures audit logging.

type Event 

type Event struct {
	ID                string         `json:"id"`
	Timestamp         time.Time      `json:"timestamp"`
	DurationMS        int64          `json:"duration_ms"`
	RequestID         string         `json:"request_id"`
	SessionID         string         `json:"session_id"`
	UserID            string         `json:"user_id"`
	UserEmail         string         `json:"user_email,omitempty"`
	Persona           string         `json:"persona,omitempty"`
	ToolName          string         `json:"tool_name"`
	ToolkitKind       string         `json:"toolkit_kind,omitempty"`
	ToolkitName       string         `json:"toolkit_name,omitempty"`
	Connection        string         `json:"connection,omitempty"`
	Parameters        map[string]any `json:"parameters,omitempty"`
	Success           bool           `json:"success"`
	ErrorMessage      string         `json:"error_message,omitempty"`
	ResponseChars     int            `json:"response_chars"`
	RequestChars      int            `json:"request_chars"`
	ContentBlocks     int            `json:"content_blocks"`
	Transport         string         `json:"transport"`
	Source            string         `json:"source"`
	EnrichmentApplied bool           `json:"enrichment_applied"`
	Authorized        bool           `json:"authorized"`
}

Event represents an auditable event.

func NewEvent 

func NewEvent(toolName string) *Event

NewEvent creates a new audit event.

func (*Event) WithAuthorized added in v0.15.0 

func (e *Event) WithAuthorized(authorized bool) *Event

WithAuthorized records the authorization decision.

func (*Event) WithConnection 

func (e *Event) WithConnection(connection string) *Event

WithConnection adds connection information to the event.

func (*Event) WithEnrichment added in v0.15.0 

func (e *Event) WithEnrichment(applied bool) *Event

WithEnrichment records whether semantic enrichment was applied.

func (*Event) WithParameters 

func (e *Event) WithParameters(params map[string]any) *Event

WithParameters adds parameters to the event.

func (*Event) WithPersona 

func (e *Event) WithPersona(persona string) *Event

WithPersona adds persona information to the event.

func (*Event) WithRequestID 

func (e *Event) WithRequestID(requestID string) *Event

WithRequestID adds a request ID to the event.

func (*Event) WithRequestSize added in v0.15.0 

func (e *Event) WithRequestSize(chars int) *Event

WithRequestSize adds request size metrics to the event.

func (*Event) WithResponseSize added in v0.14.0 

func (e *Event) WithResponseSize(chars, contentBlocks int) *Event

WithResponseSize adds response size metrics to the event.

func (*Event) WithResult 

func (e *Event) WithResult(success bool, errorMsg string, durationMS int64) *Event

WithResult adds result information to the event.

func (*Event) WithSessionID added in v0.15.0 

func (e *Event) WithSessionID(sessionID string) *Event

WithSessionID adds session identification to the event.

func (*Event) WithToolkit 

func (e *Event) WithToolkit(kind, name string) *Event

WithToolkit adds toolkit information to the event.

func (*Event) WithTransport added in v0.15.0 

func (e *Event) WithTransport(transport, source string) *Event

WithTransport adds transport and source metadata to the event.

func (*Event) WithUser 

func (e *Event) WithUser(userID, email string) *Event

WithUser adds user information to the event.

type EventType 

type EventType string

EventType categorizes audit events. 

const (
	// EventTypeToolCall is a tool invocation event.
	EventTypeToolCall EventType = "tool_call"

	// EventTypeAuth is an authentication event.
	EventTypeAuth EventType = "auth"

	// EventTypeAdmin is an administrative event.
	EventTypeAdmin EventType = "admin"
)

type Logger 

type Logger interface {
	// Log records an audit event.
	Log(ctx context.Context, event Event) error

	// Query retrieves audit events matching the filter.
	Query(ctx context.Context, filter QueryFilter) ([]Event, error)

	// Close releases resources.
	Close() error
}

Logger defines the interface for audit logging.

type Overview added in v0.17.1 

type Overview struct {
	TotalCalls     int     `json:"total_calls"`
	SuccessRate    float64 `json:"success_rate"`
	AvgDurationMS  float64 `json:"avg_duration_ms"`
	UniqueUsers    int     `json:"unique_users"`
	UniqueTools    int     `json:"unique_tools"`
	EnrichmentRate float64 `json:"enrichment_rate"`
	ErrorCount     int     `json:"error_count"`
}

Overview holds aggregate statistics for the audit log.

type PerformanceStats added in v0.17.1 

type PerformanceStats struct {
	P50MS            float64 `json:"p50_ms"`
	P95MS            float64 `json:"p95_ms"`
	P99MS            float64 `json:"p99_ms"`
	AvgMS            float64 `json:"avg_ms"`
	MaxMS            float64 `json:"max_ms"`
	AvgResponseChars float64 `json:"avg_response_chars"`
	AvgRequestChars  float64 `json:"avg_request_chars"`
}

PerformanceStats holds latency percentile statistics.

type QueryFilter 

type QueryFilter struct {
	ID          string
	StartTime   *time.Time
	EndTime     *time.Time
	UserID      string
	SessionID   string
	ToolName    string
	ToolkitKind string
	Search      string
	Success     *bool
	SortBy      string
	SortOrder   SortOrder
	Limit       int
	Offset      int
}

QueryFilter defines criteria for querying audit events.

type Resolution added in v0.17.1 

type Resolution string

Resolution defines the time bucketing granularity for timeseries queries. 

const (
	// ResolutionMinute buckets by minute.
	ResolutionMinute Resolution = "minute"

	// ResolutionHour buckets by hour.
	ResolutionHour Resolution = "hour"

	// ResolutionDay buckets by day.
	ResolutionDay Resolution = "day"
)

type SortOrder added in v0.17.1 

type SortOrder string

SortOrder defines sort direction. 

const (
	// SortAsc sorts ascending.
	SortAsc SortOrder = "asc"

	// SortDesc sorts descending.
	SortDesc SortOrder = "desc"
)

type TimeseriesBucket added in v0.17.1 

type TimeseriesBucket struct {
	Bucket        time.Time `json:"bucket"`
	Count         int       `json:"count"`
	SuccessCount  int       `json:"success_count"`
	ErrorCount    int       `json:"error_count"`
	AvgDurationMS float64   `json:"avg_duration_ms"`
}

TimeseriesBucket holds counts for a single time bucket.

type TimeseriesFilter added in v0.17.1 

type TimeseriesFilter struct {
	Resolution Resolution
	StartTime  *time.Time
	EndTime    *time.Time
}

TimeseriesFilter controls timeseries query parameters.

Source Files

View all Source files

Directories

Path Synopsis
Package postgres provides PostgreSQL storage for audit logs.
 Package postgres provides PostgreSQL storage for audit logs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.