Documentation
¶
Overview ¶
Package analytics provides the provider interface and implementations for recording analytics events from the stapler-squad web UI and backend.
Index ¶
- func OpenAnalyticsDB(ctx context.Context, dataDir string) (*ent.Client, error)
- func StartAnalyticsSubscriber(ctx context.Context, bus *events.EventBus, provider AnalyticsProvider)
- func StartRetentionEnforcer(ctx context.Context, client *ent.Client, maxRows int, maxAgeDays int, ...)
- type AnalyticsProvider
- type EscapeEventBatchWriter
- type Event
- type LogAnalyticsProvider
- type SQLiteAnalyticsProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OpenAnalyticsDB ¶ added in v1.35.0
OpenAnalyticsDB opens (or creates) the dedicated analytics.db SQLite database inside dataDir, runs auto-migration, and returns the ent client.
The returned client is configured with a single open connection to enforce SQLite's single-writer semantics and avoid "database is locked" errors. The caller is responsible for calling client.Close() on shutdown.
func StartAnalyticsSubscriber ¶ added in v1.35.0
func StartAnalyticsSubscriber(ctx context.Context, bus *events.EventBus, provider AnalyticsProvider)
StartAnalyticsSubscriber subscribes to the EventBus and records analytics events for session lifecycle changes. It runs a goroutine that exits when ctx is cancelled. Unknown event types are logged and skipped.
Mapping:
session.created → event_name="session.created", category="user_action", session_id=session.ID
session.deleted → event_name="session.deleted", category="user_action", session_id=event.SessionID
session.updated → event_name="session.status_changed" when status transitions, category="user_action", labels={"old_status","new_status"}
session.user_interaction → event_name="session.user_interaction", category="user_action"
func StartRetentionEnforcer ¶ added in v1.35.0
func StartRetentionEnforcer(ctx context.Context, client *ent.Client, maxRows int, maxAgeDays int, escapeRetentionDays int, escapeMaxRowsPerSession int)
StartRetentionEnforcer starts a background goroutine that periodically deletes analytics events that exceed the configured age or row-count limits.
- maxRows: maximum number of rows to retain; oldest rows are deleted first when the count exceeds this limit. Use 0 to disable.
- maxAgeDays: rows older than this many days are deleted unconditionally. Use 0 to disable age-based eviction.
- escapeRetentionDays: escape_event rows older than this many days are deleted. Use 0 to disable escape event age-based eviction.
The goroutine exits when ctx is cancelled.
Types ¶
type AnalyticsProvider ¶ added in v1.35.0
AnalyticsProvider is the interface for recording analytics events. Implementations include SQLiteAnalyticsProvider (production) and LogAnalyticsProvider (testing / fallback).
type EscapeEventBatchWriter ¶ added in v1.35.0
type EscapeEventBatchWriter struct {
// contains filtered or unexported fields
}
EscapeEventBatchWriter persists escape events to SQLite via batched ent writes. It implements pkganalytics.EscapeEventWriter.
func NewEscapeEventBatchWriter ¶ added in v1.35.0
func NewEscapeEventBatchWriter(client *ent.Client, maxRowsPerSession int) *EscapeEventBatchWriter
NewEscapeEventBatchWriter creates a new batch writer. Call Start to begin processing.
func (*EscapeEventBatchWriter) DroppedCount ¶ added in v1.35.0
func (w *EscapeEventBatchWriter) DroppedCount() int64
DroppedCount returns the number of events dropped due to backpressure.
func (*EscapeEventBatchWriter) Start ¶ added in v1.35.0
func (w *EscapeEventBatchWriter) Start(ctx context.Context)
Start begins the background flush goroutine. Returns when ctx is cancelled.
func (*EscapeEventBatchWriter) WriteEscapeEvent ¶ added in v1.35.0
func (w *EscapeEventBatchWriter) WriteEscapeEvent(_ context.Context, event pkganalytics.EscapeEventRecord)
WriteEscapeEvent enqueues an event. Non-blocking: drops if channel is full.
type Event ¶ added in v1.35.0
type Event struct {
ID string
EventName string
EventCategory string
SessionID string
DurationMs *int64
Page string
Component string
Labels map[string]string
}
Event represents a single analytics event to be recorded.
type LogAnalyticsProvider ¶ added in v1.35.0
type LogAnalyticsProvider struct{}
LogAnalyticsProvider is a no-op analytics provider that logs events instead of persisting them. It is used as a fallback when the database fails to open and as a convenient substitute in unit tests.
func NewLogAnalyticsProvider ¶ added in v1.35.0
func NewLogAnalyticsProvider() *LogAnalyticsProvider
NewLogAnalyticsProvider creates a LogAnalyticsProvider.
type SQLiteAnalyticsProvider ¶ added in v1.35.0
type SQLiteAnalyticsProvider struct {
// contains filtered or unexported fields
}
SQLiteAnalyticsProvider records analytics events to a dedicated SQLite database via the ent ORM. It is safe for concurrent use — the underlying ent client serialises all writes through a single connection (MaxOpenConns=1).
func NewSQLiteAnalyticsProvider ¶ added in v1.35.0
func NewSQLiteAnalyticsProvider(client *ent.Client) *SQLiteAnalyticsProvider
NewSQLiteAnalyticsProvider creates a new SQLiteAnalyticsProvider backed by client. The caller retains ownership of client and must close it on shutdown.
func (*SQLiteAnalyticsProvider) Record ¶ added in v1.35.0
func (p *SQLiteAnalyticsProvider) Record(ctx context.Context, event Event) error
Record inserts a single analytics event into the database. If event.ID is empty, a new UUID is generated automatically. Optional fields (SessionID, DurationMs, Page, Component, Labels) are skipped when zero/nil so the database stores NULLs rather than empty strings.
Source Files