Documentation
¶
Overview ¶
Package usage records and aggregates token-usage statistics across all jcode surfaces (TUI, web, ACP). It uses an append-only JSON-lines event log (~/.jcode/usage/events.jsonl), one line per agent turn. Append-only writes are atomic for small records under O_APPEND, so multiple jcode processes can record concurrently without a read-modify-write race; all derived metrics are computed at read time by Aggregate.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EstimateBytes ¶
EstimateBytes approximates the token count of a byte length.
func RecordEvent ¶
func RecordEvent(ev Event)
RecordEvent stamps ev with the current time and appends it to the default store. Callers fill in the session/project/model + token deltas; TS/Date are set here. Best-effort: errors are swallowed so stats never break a run.
Types ¶
type Aggregated ¶
type Aggregated struct {
Totals Totals
ActiveDays int
CurrentStreak int
LongestStreak int
MostUsedModel string
CacheHitRate float64 // cached / prompt, clamped to [0,1]
CacheSupported bool
Days map[string]*DayBucket
ByModel []Share
ByProject []Share
}
Aggregated is the full derived view over a set of events.
func Aggregate ¶
func Aggregate(events []Event, today string) Aggregated
Aggregate reduces raw events into derived statistics. `today` (YYYY-MM-DD, local) anchors the current-streak computation so the function stays pure and testable.
func (Aggregated) Trend ¶
func (a Aggregated) Trend() []DayBucket
Trend returns the day buckets in ascending date order.
type ContextBreakdown ¶
type ContextBreakdown struct {
SystemPromptTokens int `json:"system_prompt_tokens"`
SystemToolsTokens int `json:"system_tools_tokens"`
MCPToolsTokens int `json:"mcp_tools_tokens"`
SkillsTokens int `json:"skills_tokens"`
MessagesTokens int `json:"messages_tokens"`
ContextLimit int `json:"context_limit"`
}
ContextBreakdown partitions a context window into the categories that make it up. The four static buckets (system prompt / tools / MCP tools / skills) are computed from the live agent assembly; MessagesTokens and ContextLimit are filled in at query time.
func (ContextBreakdown) StaticTotal ¶
func (b ContextBreakdown) StaticTotal() int
StaticTotal is the sum of the four assembly-time buckets (everything except the conversation messages).
type DayBucket ¶
type DayBucket struct {
Date string `json:"date"`
Tokens int64 `json:"tokens"`
Turns int64 `json:"turns"` // recorded turns ("轮") that day
Calls int64 `json:"calls"`
}
DayBucket is one day's rolled-up usage.
type Event ¶
type Event struct {
TS int64 `json:"ts"` // unix seconds
Date string `json:"date"` // YYYY-MM-DD, local time
Project string `json:"project,omitempty"`
Session string `json:"session,omitempty"` // session UUID
Model string `json:"model,omitempty"`
Prompt int `json:"prompt"`
Completion int `json:"completion"`
Cached int `json:"cached"`
Reasoning int `json:"reasoning,omitempty"`
CacheWrite int `json:"cache_write,omitempty"`
Total int `json:"total"`
Calls int `json:"calls,omitempty"` // API calls in this turn
}
Event is a single recorded agent turn's token usage. Token fields are the per-turn delta (not cumulative).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is an append-only event-log writer/reader.
func Default ¶
func Default() *Store
Default returns the process-wide store bound to ~/.jcode/usage/events.jsonl. If the path cannot be resolved, the returned store is a no-op.
type Totals ¶
type Totals struct {
Total int64 `json:"total"`
Prompt int64 `json:"prompt"`
Completion int64 `json:"completion"`
Cached int64 `json:"cached"`
Reasoning int64 `json:"reasoning"`
CacheWrite int64 `json:"cache_write"`
Calls int64 `json:"calls"`
Turns int64 `json:"turns"` // number of recorded events
}
Totals holds cumulative token counters over the aggregated window.
Source Files