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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultPath ¶
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 NewAt ¶
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 ¶
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) Prune ¶
Prune deletes events older than the configured retention period. Returns the number of rows deleted.
func (*Tracker) Record ¶
Record adds a new compression event. The ID and SavingsPct fields of ev are ignored; SavingsPct is computed from byte counts.
func (*Tracker) WithRetention ¶
WithRetention overrides the default 90-day retention period. Must be called before any Record or Aggregate call.
Source Files