analytics

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
  • func NewEscapeEventBatchWriter(client *ent.Client, maxRowsPerSession int) *EscapeEventBatchWriter
  • func (w *EscapeEventBatchWriter) DroppedCount() int64
  • func (w *EscapeEventBatchWriter) Start(ctx context.Context)
  • func (w *EscapeEventBatchWriter) WriteEscapeEvent(_ context.Context, event pkganalytics.EscapeEventRecord)
• type Event
• type LogAnalyticsProvider
  • func NewLogAnalyticsProvider() *LogAnalyticsProvider
  • func (p *LogAnalyticsProvider) Record(_ context.Context, event Event) error
• type SQLiteAnalyticsProvider
  • func NewSQLiteAnalyticsProvider(client *ent.Client) *SQLiteAnalyticsProvider
  • func (p *SQLiteAnalyticsProvider) Record(ctx context.Context, event Event) error

Functions

func OpenAnalyticsDB

func OpenAnalyticsDB(ctx context.Context, dataDir string) (*ent.Client, error)

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

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

func StartRetentionEnforcer(ctx context.Context, client *ent.Client, maxRows int, maxAgeDays int, escapeRetentionDays 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

type AnalyticsProvider interface {
	Record(ctx context.Context, event Event) error
}

AnalyticsProvider is the interface for recording analytics events. Implementations include SQLiteAnalyticsProvider (production) and LogAnalyticsProvider (testing / fallback).

type EscapeEventBatchWriter

type EscapeEventBatchWriter struct {
	// contains filtered or unexported fields
}

EscapeEventBatchWriter persists escape events to SQLite via batched ent writes. It implements pkganalytics.EscapeEventWriter.

func NewEscapeEventBatchWriter

func NewEscapeEventBatchWriter(client *ent.Client, maxRowsPerSession int) *EscapeEventBatchWriter

NewEscapeEventBatchWriter creates a new batch writer. Call Start to begin processing.

func (*EscapeEventBatchWriter) DroppedCount

func (w *EscapeEventBatchWriter) DroppedCount() int64

DroppedCount returns the number of events dropped due to backpressure.

func (*EscapeEventBatchWriter) Start

func (w *EscapeEventBatchWriter) Start(ctx context.Context)

Start begins the background flush goroutine. Returns when ctx is cancelled.

func (*EscapeEventBatchWriter) WriteEscapeEvent

func (w *EscapeEventBatchWriter) WriteEscapeEvent(_ context.Context, event pkganalytics.EscapeEventRecord)

WriteEscapeEvent enqueues an event. Non-blocking: drops if channel is full.

type Event

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

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

func NewLogAnalyticsProvider() *LogAnalyticsProvider

NewLogAnalyticsProvider creates a LogAnalyticsProvider.

func (*LogAnalyticsProvider) Record

func (p *LogAnalyticsProvider) Record(_ context.Context, event Event) error

Record logs the event using slog.Default() and returns nil.

type SQLiteAnalyticsProvider

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

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

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.