usage

Documentation

Overview

Package usage tracks LLM/embedding token usage, aggregated per day and persisted through a caller-supplied flush callback.

Index

• type Tracker
  • func NewTracker(persist func(date string, u Usage) error, flushInterval time.Duration) *Tracker
  • func (t *Tracker) Add(u Usage)
  • func (t *Tracker) Close()
  • func (t *Tracker) Today() (string, Usage)
• type Usage

Types

type Tracker

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

Tracker accumulates usage for the current UTC day and persists aggregated deltas through the flush callback (day-scoped, so the callback upserts one row). With a positive flushInterval deltas are batched and flushed on a timer (reducing SQLite write amplification); interval <= 0 persists synchronously on every Add (backwards-compatible). It is safe for concurrent use.

func NewTracker

func NewTracker(persist func(date string, u Usage) error, flushInterval time.Duration) *Tracker

NewTracker builds a Tracker. persist is called with the current date key and the aggregated delta (best-effort; errors are ignored). flushInterval <= 0 runs in synchronous mode (persist once per Add); otherwise a background goroutine flushes every flushInterval and Close flushes any remainder.

func (*Tracker) Add

func (t *Tracker) Add(u Usage)

Add accumulates a usage delta for the current day. In sync mode (interval <= 0) it persists the delta immediately; otherwise the delta is batched until the next flush. On a day rollover the in-memory accumulator resets (the persisted rows keep the per-day history).

func (*Tracker) Close

func (t *Tracker) Close()

Close stops the background flusher and persists any pending delta. It is a no-op in sync mode (interval <= 0). Safe to call once.

func (*Tracker) Today

func (t *Tracker) Today() (string, Usage)

Today returns the current day key and its accumulated in-memory usage (including deltas not yet flushed).

type Usage

type Usage struct {
	Input    int64 // prompt/input tokens
	Output   int64 // completion/output tokens
	CacheHit int64 // input tokens served from the provider's prompt cache
}

Usage is a single token-usage delta.