usage

Documentation

Index

• Constants
• func AggregateByModel(records []*Record) map[string]*ModelStats
• func AggregateByRoute(records []*Record) map[string]*RouteStats
• func DBPath() (string, error)
• func DeleteAllRecords(db *sql.DB) (int64, error)
• func FormatTokens(tokens int) string
• func FormatUsage(w io.Writer, instanceID, period string, records []*Record)
• func InitDB(path string) (*sql.DB, error)
• func InsertRecord(db dbExecutor, r *Record) error
• func ParsePeriod(period string, now time.Time) (start, end time.Time, err error)
• func PruneRecords(db *sql.DB, before time.Time) (int64, error)
• type ModelStats
• type Record
  • func GetRecordsByPeriod(db *sql.DB, instanceID string, start, end time.Time) ([]*Record, error)
• type RouteStats
• type Summary
  • func AggregateSummary(records []*Record) Summary
• type Tracker
  • func NewTracker(db *sql.DB, bufferSize int, flushTimeout time.Duration) *Tracker
  • func (t *Tracker) Record(instanceID, route, model, profile, provider string, tokens, fallbacks int)
  • func (t *Tracker) Shutdown()

Constants

const (
	DefaultBufferSize   = 500
	DefaultFlushTimeout = 1 * time.Second // Reduced from 3s for near-realtime monitor updates

)

Functions

func AggregateByModel

func AggregateByModel(records []*Record) map[string]*ModelStats

AggregateByModel groups records by profile/provider.model.

func AggregateByRoute

func AggregateByRoute(records []*Record) map[string]*RouteStats

AggregateByRoute groups records by profile/provider.route.

func DBPath

func DBPath() (string, error)

DBPath returns the path to the usage database.

func DeleteAllRecords

func DeleteAllRecords(db *sql.DB) (int64, error)

DeleteAllRecords deletes all usage records and reclaims disk space.

func FormatTokens

func FormatTokens(tokens int) string

FormatTokens formats a token count for display.

func FormatUsage

func FormatUsage(w io.Writer, instanceID, period string, records []*Record)

FormatUsage writes formatted usage statistics to the writer.

func InitDB

func InitDB(path string) (*sql.DB, error)

InitDB initializes the usage database.

func InsertRecord

func InsertRecord(db dbExecutor, r *Record) error

InsertRecord inserts a usage record.

func ParsePeriod

func ParsePeriod(period string, now time.Time) (start, end time.Time, err error)

ParsePeriod converts a period string to start and end times.

func PruneRecords

func PruneRecords(db *sql.DB, before time.Time) (int64, error)

PruneRecords deletes usage records older than the given time and reclaims disk space.

Types

type ModelStats

type ModelStats struct {
	Profile  string
	Model    string
	Requests int
	Tokens   int
}

ModelStats represents stats for a single model.

type Record

type Record struct {
	ID         int64
	InstanceID string
	Profile    string // active route profile name
	Provider   string // provider that handled the request
	Route      string
	Model      string
	Tokens     int
	Fallbacks  int
	Timestamp  time.Time
}

Record represents a usage record.

func GetRecordsByPeriod

func GetRecordsByPeriod(db *sql.DB, instanceID string, start, end time.Time) ([]*Record, error)

GetRecordsByPeriod retrieves records within a time range, optionally filtered by instance.

type RouteStats

type RouteStats struct {
	Profile   string
	Route     string
	Requests  int
	Tokens    int
	Fallbacks int
}

RouteStats represents stats for a single route.

type Summary

type Summary struct {
	TotalRequests  int
	TotalTokens    int
	TotalFallbacks int
}

Summary represents aggregated usage summary.

func AggregateSummary

func AggregateSummary(records []*Record) Summary

AggregateSummary computes overall summary from records.

type Tracker

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

Tracker tracks usage records in memory and flushes to database. Uses a buffered channel for lock-free submission on the hot path, with a single goroutine handling batching and SQLite writes.

func NewTracker

func NewTracker(db *sql.DB, bufferSize int, flushTimeout time.Duration) *Tracker

NewTracker creates a new usage tracker.

func (*Tracker) Record

func (t *Tracker) Record(instanceID, route, model, profile, provider string, tokens, fallbacks int)

Record adds a usage record via a buffered channel. Zero mutex contention on the hot path — the single flushLoop goroutine handles all SQLite writes.

func (*Tracker) Shutdown

func (t *Tracker) Shutdown()

Shutdown flushes remaining records and stops the tracker.