README
¶
meter
Usage metering for AI API calls. Records per-call usage (tokens, images, audio seconds, video seconds) and provides aggregation and query capabilities. This package measures usage only; cost calculation is left to the consuming application.
Key Types
Usage-- metering data for a single call (input/output/cached/reasoning tokens, image count, audio/video seconds, request count). Has aMergemethod.UsageRecord-- a stored metering event with provider, model, mode, usage, and timestamp.UsageQuery-- filter for querying records (provider, model, mode, time range).UsageStats-- aggregated summary with totals and breakdowns by provider/model/mode.UsageAggregate-- one bucket in a grouped aggregation.Meter-- interface withRecord,Query,Aggregate, andClosemethods.
Implementations
NewMemoryMeter-- in-memory implementation suitable for testing and single-process usage.
Usage
m := meter.NewMemoryMeter()
defer m.Close()
m.Record(ctx, &meter.UsageRecord{
Provider: "openai",
Model: "gpt-4o-mini",
Usage: meter.Usage{InputTokens: 100, OutputTokens: 50, TotalTokens: 150},
})
stats, _ := m.Query(ctx, nil)
agg, _ := m.Aggregate(ctx, nil, "model")
Documentation
¶
Overview ¶
Package meter provides usage metering for AI API calls. It records per-call usage (tokens, images, audio seconds, video seconds) and provides aggregation/query capabilities.
This package focuses on **metering** (how much was used), not pricing. Cost calculation is intentionally left out — the consuming application can compute cost from usage data using its own pricing rules.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Meter ¶
type Meter interface {
// Record stores a usage event.
Record(ctx context.Context, record *UsageRecord) error
// Query returns aggregated usage statistics matching the query.
Query(ctx context.Context, q *UsageQuery) (*UsageStats, error)
// Aggregate groups usage by the given dimension ("provider", "model", "mode").
Aggregate(ctx context.Context, q *UsageQuery, groupBy string) ([]UsageAggregate, error)
// Close releases resources.
Close() error
}
Meter is the interface for recording and querying usage.
type Usage ¶
type Usage struct {
// Token counts (text models).
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
TotalTokens int `json:"total_tokens"`
CachedTokens int `json:"cached_tokens,omitempty"` // prompt cache hit
// Cache creation tokens (Claude-specific).
CacheCreationTokens int `json:"cache_creation_tokens,omitempty"`
CacheCreation5m int `json:"cache_creation_5m_tokens,omitempty"`
CacheCreation1h int `json:"cache_creation_1h_tokens,omitempty"`
// Reasoning/thinking tokens.
ReasoningTokens int `json:"reasoning_tokens,omitempty"`
// Non-text modality counts.
ImageCount int `json:"image_count,omitempty"`
AudioSeconds float64 `json:"audio_seconds,omitempty"`
VideoSeconds float64 `json:"video_seconds,omitempty"`
// Request count (for async tasks and other non-token calls).
RequestCount int `json:"request_count,omitempty"`
// Source provider format, for debugging.
Source string `json:"source,omitempty"`
}
Usage holds metering data for a single API call. All providers must populate this struct in their response handling.
type UsageAggregate ¶
type UsageAggregate struct {
Key string `json:"key"`
Usage Usage `json:"usage"`
Count int `json:"count"`
}
UsageAggregate is one bucket in a grouped aggregation.
type UsageQuery ¶
UsageQuery filters usage records.
type UsageRecord ¶
type UsageRecord struct {
ID string `json:"id,omitempty"`
Provider string `json:"provider"`
Model string `json:"model"`
Mode int `json:"mode,omitempty"` // relay mode
Usage Usage `json:"usage"`
Timestamp time.Time `json:"timestamp"`
}
UsageRecord is a stored metering event.
type UsageStats ¶
type UsageStats struct {
TotalRecords int `json:"total_records"`
TotalUsage Usage `json:"total_usage"`
ByProvider map[string]Usage `json:"by_provider,omitempty"`
ByModel map[string]Usage `json:"by_model,omitempty"`
ByMode map[int]Usage `json:"by_mode,omitempty"`
TimeRange [2]time.Time `json:"time_range,omitempty"`
}
UsageStats is an aggregated usage summary.
Source Files