tracking

Documentation

Overview

Package tracking provides persistent gain tracking for tok compression calls via a local SQLite database.

Each compression event is recorded with timestamp, command name, original/compressed byte and token counts, savings percentage, mode, and model. The tracker exposes aggregate queries for dashboards and budget enforcement.

Storage defaults to ~/.tok/tracker.db with WAL mode and a 90-day retention policy (configurable per Tracker instance).

GrayCode native gain-tracking implementation. using modernc.org/sqlite (pure Go, no CGO).

Package tracking: platform-specific helpers.

Index

• func DefaultPath() (string, error)
• type Aggregate
• type Event
• type Tracker
  • func New(ctx context.Context) (*Tracker, error)
  • func NewAt(ctx context.Context, path string) (*Tracker, error)
  • func (t *Tracker) Aggregate(ctx context.Context, days int) (Aggregate, error)
  • func (t *Tracker) Close() error
  • func (t *Tracker) Prune(ctx context.Context) (int64, error)
  • func (t *Tracker) Recent(ctx context.Context, n int) ([]Event, error)
  • func (t *Tracker) Record(ctx context.Context, ev Event) error
  • func (t *Tracker) WithRetention(days int) *Tracker

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the default tracker DB path (~/.tok/tracker.db). Returns the path and a non-nil error only if the home directory cannot be determined.

Types

type Aggregate

type Aggregate struct {
	EventCount      int
	TotalBytesSaved int
	AvgSavingsPct   float64
	PeriodStart     time.Time
	PeriodEnd       time.Time
}

Aggregate is the result of a Tracker.Aggregate call.

type Event

type Event struct {
	ID               int64
	Timestamp        time.Time
	Command          string
	OriginalBytes    int
	CompressedBytes  int
	OriginalTokens   int
	CompressedTokens int
	Mode             string
	Tier             string
	Model            string
	// Computed in DB query; not stored.
	SavingsPct float64
}

Event is a single compression event recorded by the tracker.

type Tracker

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

Tracker is the public type. Construct with New() or NewAt(path).

func New

func New(ctx context.Context) (*Tracker, error)

New creates a tracker at the default path.

func NewAt

func NewAt(ctx context.Context, path string) (*Tracker, error)

NewAt creates a tracker at the given path. The parent directory is created if it does not exist. WAL journal mode is enabled and the schema is created on first call.

func (*Tracker) Aggregate

func (t *Tracker) Aggregate(ctx context.Context, days int) (Aggregate, error)

Aggregate returns aggregate stats over the last `days` days (or the configured retention period if days is 0). Empty result if no events in the window.

func (*Tracker) Close

func (t *Tracker) Close() error

Close closes the underlying DB. Safe to call multiple times.

func (*Tracker) Prune

func (t *Tracker) Prune(ctx context.Context) (int64, error)

Prune deletes events older than the configured retention period. Returns the number of rows deleted.

func (*Tracker) Recent

func (t *Tracker) Recent(ctx context.Context, n int) ([]Event, error)

Recent returns the most recent n events, newest first.

func (*Tracker) Record

func (t *Tracker) Record(ctx context.Context, ev Event) error

Record adds a new compression event. The ID and SavingsPct fields of ev are ignored; SavingsPct is computed from byte counts.

func (*Tracker) WithRetention

func (t *Tracker) WithRetention(days int) *Tracker

WithRetention overrides the default 90-day retention period. Must be called before any Record or Aggregate call.