Help us shape the future of Go! Take the 2026 Go Developer Survey

audit

package
v1.79.0 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 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,
	"source":             true,
	"connection":         true,
	"duration_ms":        true,
	"success":            true,
	"enrichment_applied": true,
	"enrichment_mode":    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" example:"trino_query"`
	Count         int     `json:"count" example:"65"`
	SuccessRate   float64 `json:"success_rate" example:"0.95"`
	AvgDurationMS float64 `json:"avg_duration_ms" example:"320.0"`
}

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
	UserID    string
	// ToolName scopes the aggregation to a specific tool. Set when a
	// caller wants per-tool stats regardless of breakdown ranking — on
	// platforms with more than Limit distinct tools active in the
	// window, low-frequency tools would otherwise fall off the top-N
	// breakdown and appear as "no calls recorded" even when they have
	// activity (#343 bug 2).
	ToolName string
	// EventKind scopes the aggregation to a specific event category.
	// Lets the portal MCP view exclude apigateway noise without
	// modifying the breakdown call sites.
	EventKind string
}

BreakdownFilter controls breakdown query parameters.

type Config 

type Config struct {
	Enabled       bool
	LogToolCalls  bool
	RetentionDays int
}

Config configures audit logging.

type DiscoveryStats added in v0.25.0 

type DiscoveryStats struct {
	TotalSessions         int              `json:"total_sessions" example:"100"`
	DiscoverySessions     int              `json:"discovery_sessions" example:"75"`
	QuerySessions         int              `json:"query_sessions" example:"80"`
	DiscoveryBeforeQuery  int              `json:"discovery_before_query" example:"60"`
	DiscoveryRate         float64          `json:"discovery_rate" example:"0.75"`
	QueryWithoutDiscovery int              `json:"query_without_discovery" example:"20"`
	TopDiscoveryTools     []BreakdownEntry `json:"top_discovery_tools"`
}

DiscoveryStats holds discovery-before-query pattern statistics.

type EnrichmentStats added in v0.25.0 

type EnrichmentStats struct {
	TotalCalls       int     `json:"total_calls" example:"1500"`
	EnrichedCalls    int     `json:"enriched_calls" example:"1200"`
	EnrichmentRate   float64 `json:"enrichment_rate" example:"0.80"`
	FullCount        int     `json:"full_count" example:"800"`
	SummaryCount     int     `json:"summary_count" example:"300"`
	ReferenceCount   int     `json:"reference_count" example:"100"`
	NoneCount        int     `json:"none_count" example:"0"`
	TotalTokensFull  int64   `json:"total_tokens_full" example:"450000"`
	TotalTokensDedup int64   `json:"total_tokens_dedup" example:"120000"`
	TokensSaved      int64   `json:"tokens_saved" example:"330000"`
	AvgTokensFull    float64 `json:"avg_tokens_full" example:"375.0"`
	AvgTokensDedup   float64 `json:"avg_tokens_dedup" example:"100.0"`
	UniqueSessions   int     `json:"unique_sessions" example:"45"`
}

EnrichmentStats holds aggregate enrichment statistics.

type Event 

type Event struct {
	ID                    string         `json:"id" example:"evt_a1b2c3d4e5f6"`
	Timestamp             time.Time      `json:"timestamp" example:"2026-04-15T10:41:18Z"`
	DurationMS            int64          `json:"duration_ms" example:"143"`
	RequestID             string         `json:"request_id" example:"req_x9y8z7"`
	SessionID             string         `json:"session_id" example:"sess_abc123"`
	UserID                string         `json:"user_id" example:"550e8400-e29b-41d4-a716-446655440000"`
	UserEmail             string         `json:"user_email,omitempty" example:"marcus.johnson@example.com"`
	Persona               string         `json:"persona,omitempty" example:"data-engineer"`
	ToolName              string         `json:"tool_name" example:"datahub_get_schema"`
	ToolkitKind           string         `json:"toolkit_kind,omitempty" example:"datahub"`
	ToolkitName           string         `json:"toolkit_name,omitempty" example:"acme-catalog"`
	Connection            string         `json:"connection,omitempty" example:"acme-catalog"`
	Parameters            map[string]any `json:"parameters,omitempty"`
	Success               bool           `json:"success" example:"true"`
	ErrorMessage          string         `json:"error_message,omitempty"`
	ResponseChars         int            `json:"response_chars" example:"2450"`
	RequestChars          int            `json:"request_chars" example:"120"`
	ContentBlocks         int            `json:"content_blocks" example:"2"`
	Transport             string         `json:"transport" example:"http"`
	Source                string         `json:"source" example:"mcp"`
	EnrichmentApplied     bool           `json:"enrichment_applied" example:"true"`
	EnrichmentTokensFull  int            `json:"enrichment_tokens_full" example:"850"`
	EnrichmentTokensDedup int            `json:"enrichment_tokens_dedup" example:"350"`
	EnrichmentMode        string         `json:"enrichment_mode,omitempty" example:"summary"`
	// EnrichmentMatchKind records how the semantic enrichment matched
	// the target table or column: "urn" when the URN-equality lookup
	// resolved exactly, "semantic" when an exact lookup missed and the
	// platform fell back to similarity search (suggested match, not
	// asserted), or empty when no enrichment ran. Operators use this
	// to measure the false-positive rate of similarity-based
	// suggestions (issue #444).
	EnrichmentMatchKind string `json:"enrichment_match_kind,omitempty" example:"urn"`
	Authorized          bool   `json:"authorized" example:"true"`
	// EventKind is the high-level category of the event. Set to
	// "mcp_tool_call" for tools routed through the MCP toolkits (trino,
	// datahub, s3, mcp gateway) and "apigateway_invoke" for upstream
	// HTTP API calls via the apigateway toolkit. Lets the portal split
	// MCP activity from gateway noise without coupling to tool-name
	// patterns. See EventType constants in event.go.
	EventKind EventType `json:"event_kind,omitempty" example:"mcp_tool_call"`
}

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) WithEnrichmentMatchKind added in v1.67.0 

func (e *Event) WithEnrichmentMatchKind(kind string) *Event

WithEnrichmentMatchKind records how enrichment matched its target: "urn" for exact URN equality, "semantic" for similarity-fallback, empty when no enrichment ran. See Event.EnrichmentMatchKind.

func (*Event) WithEnrichmentMode added in v0.25.0 

func (e *Event) WithEnrichmentMode(mode string) *Event

WithEnrichmentMode records the enrichment mode used for this event.

func (*Event) WithEnrichmentTokens added in v0.24.0 

func (e *Event) WithEnrichmentTokens(full, dedup int) *Event

WithEnrichmentTokens records estimated token counts for enrichment.

func (*Event) WithEventKind added in v1.69.0 

func (e *Event) WithEventKind(kind EventType) *Event

WithEventKind records the high-level category of the event (e.g. mcp_tool_call, apigateway_invoke). See Event.EventKind.

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"

	// EventTypeMCPToolCall categorizes an MCP tool invocation routed
	// through a non-apigateway toolkit (trino, datahub, s3, mcp gateway).
	// Stamped into Event.EventKind at write time so the portal Activity
	// view can exclude apigateway HTTP noise by default.
	EventTypeMCPToolCall EventType = "mcp_tool_call"

	// EventTypeAPIGatewayInvoke categorizes an HTTP API invocation
	// through the apigateway toolkit. Stamped into Event.EventKind at
	// write time so the portal Activity view can split these out from
	// the MCP-only view.
	EventTypeAPIGatewayInvoke EventType = "apigateway_invoke"
)

func EventKindForToolkit added in v1.69.0 

func EventKindForToolkit(toolkitKind string) EventType

EventKindForToolkit maps a toolkit kind to its high-level event category. The apigateway toolkit ("api") produces HTTP invocations; every other toolkit kind produces MCP tool calls. Used at audit write time so the portal can split gateway noise from MCP activity.

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 MetricsFilter added in v0.36.0 

type MetricsFilter struct {
	StartTime *time.Time
	EndTime   *time.Time
	UserID    string
	EventKind string
}

MetricsFilter provides common filtering for aggregate metric queries.

type Overview added in v0.17.1 

type Overview struct {
	TotalCalls     int     `json:"total_calls" example:"196"`
	SuccessRate    float64 `json:"success_rate" example:"0.949"`
	AvgDurationMS  float64 `json:"avg_duration_ms" example:"522"`
	UniqueUsers    int     `json:"unique_users" example:"12"`
	UniqueTools    int     `json:"unique_tools" example:"12"`
	EnrichmentRate float64 `json:"enrichment_rate" example:"0.85"`
	ErrorCount     int     `json:"error_count" example:"10"`
}

Overview holds aggregate statistics for the audit log.

type PerformanceStats added in v0.17.1 

type PerformanceStats struct {
	P50MS            float64 `json:"p50_ms" example:"320"`
	P95MS            float64 `json:"p95_ms" example:"1450"`
	P99MS            float64 `json:"p99_ms" example:"2400"`
	AvgMS            float64 `json:"avg_ms" example:"522"`
	MaxMS            float64 `json:"max_ms" example:"5200"`
	AvgResponseChars float64 `json:"avg_response_chars" example:"1850"`
	AvgRequestChars  float64 `json:"avg_request_chars" example:"120"`
}

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
	Source      string
	EventKind   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" example:"2026-04-15T14:30:00Z"`
	Count         int       `json:"count" example:"12"`
	SuccessCount  int       `json:"success_count" example:"11"`
	ErrorCount    int       `json:"error_count" example:"1"`
	AvgDurationMS float64   `json:"avg_duration_ms" example:"245.5"`
}

TimeseriesBucket holds counts for a single time bucket.

func ZeroFill added in v0.36.1 

func ZeroFill(buckets []TimeseriesBucket, start, end time.Time, resolution Resolution) []TimeseriesBucket

ZeroFill expands a sparse set of timeseries buckets into a complete series covering [start, end] at the given resolution. Missing buckets are filled with zero values.

type TimeseriesFilter added in v0.17.1 

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

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.