Files
llmgw/internal/store/usageseries.go
T
Ilker ManapandClaude Opus 5 07809490e3
CI / test (push) Has been cancelled
Show usage over time, per organization, team, project and person
Usage could be read as a total — per key, per user, per model, per group —
and the cluster's own charts covered the fleet's hardware. What nobody could
see was when a group used it. "Research doubled its traffic three weeks ago"
is not a question a column of totals can be asked, and it is the question
somebody asks before a quota conversation.

/admin/usage draws requests, tokens and spend over a chosen window, grouped
by any level of the tenancy tree or by person. Person is not a level of that
tree — one person holds keys in several projects — so the grouping is its
own type rather than store.Scope with a fourth value nothing else could use.

Three things learned from the charts already here. Buckets are gap-filled
per group, because a line drawn straight across an absence claims traffic
that did not happen, and because the chart sums its tail by timestamp and
can only do that if every series shares a clock. Series are ranked by total
rather than by peak — a counter's question is "who used the most", and
ranking by peak would colour the team that made one burst over the team that
ran steadily all week. And the spend chart is replaced by a sentence when no
model has a price, rather than drawn flat along the bottom.

The bucket query groups by ordinal and was planned against the cluster's
PostgreSQL before being believed, with a test alongside the others that run
there: three reports have shipped working on SQLite and failing on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-28 08:11:31 +02:00

186 lines
5.8 KiB
Go

package store
import (
"context"
"fmt"
"time"
)
// Grouping is how a usage report is broken down.
//
// Not store.Scope with one more value, although three of the four agree with
// it. Scope is where a limit hangs, and nothing hangs off a person: one person
// holds keys in several projects, so a per-user total crosses the tree rather
// than naming a level of it. Keeping the two apart means neither has to carry a
// case the other does not have.
type Grouping string
// The groupings a usage report can be asked for.
const (
GroupByOrg Grouping = "org"
GroupByTeam Grouping = "team"
GroupByProject Grouping = "project"
GroupByUser Grouping = "user"
)
// Valid reports whether this is a grouping usage can be read by.
func (g Grouping) Valid() bool {
_, ok := groupColumns[g]
return ok
}
// Groupings lists them in the order a page should offer them: widest first,
// then the one that is not a level at all.
func Groupings() []Grouping {
return []Grouping{GroupByOrg, GroupByTeam, GroupByProject, GroupByUser}
}
// UsageSeries is one group's usage over time.
//
// Buckets are contiguous and gap-filled: a group that stopped using the cluster
// has zeroes rather than an absence, because a line drawn straight across a gap
// says the traffic continued. It also means every series in a report shares one
// set of timestamps, which is what lets a chart sum the tail of them.
type UsageSeries struct {
Grouping Grouping
ID string
Name string
Buckets []Bucket
// Totals over the whole window, so a table beside the chart does not have
// to add the buckets up and possibly disagree with them.
Requests int64
Prompt int64
Completion int64
CostMicros int64
Errors int64
}
// Tokens is what the group consumed, prompt and completion together.
func (u UsageSeries) Tokens() int64 { return u.Prompt + u.Completion }
// groupColumns is the id and display name for each grouping, and how usage
// reaches it.
//
// Written out per grouping rather than assembled from parts: these are table
// and column names going into SQL, and the one place they must not come from
// anywhere but here is the place they are interpolated. A grouping that is not
// in this map is refused before a query is built.
//
// Joined through api_keys rather than read from usage.project_id, for the same
// reason UsageByScope is: that column records where the key was when the
// request was served, and the tree is what a quota is written against. They
// agree until a key is moved, and a report that disagrees with the limit shown
// beside it is the useless one.
var groupColumns = map[Grouping]struct{ id, name, joins string }{
GroupByOrg: {"o.id", "o.name", `
JOIN api_keys k ON k.id = u.key_id
JOIN projects p ON p.id = k.project_id
JOIN teams t ON t.id = p.team_id
JOIN organizations o ON o.id = t.org_id`},
GroupByTeam: {"t.id", "t.name", `
JOIN api_keys k ON k.id = u.key_id
JOIN projects p ON p.id = k.project_id
JOIN teams t ON t.id = p.team_id`},
GroupByProject: {"p.id", "p.name", `
JOIN api_keys k ON k.id = u.key_id
JOIN projects p ON p.id = k.project_id`},
// Left joins, and coalesced: a key issued by an operator before accounts
// existed has no owner, and its traffic is real. It groups under an empty
// id, which the page names rather than hides.
GroupByUser: {"COALESCE(k.user_id, '')", "COALESCE(us.email, '')", `
LEFT JOIN api_keys k ON k.id = u.key_id
LEFT JOIN users us ON us.id = k.user_id`},
}
// UsageBucketsBy returns each group's usage over time.
//
// One query for every group rather than one per group: the page shows them
// together, and a query per organization is a loop whose cost grows with the
// thing being reported on.
func (s *DB) UsageBucketsBy(
ctx context.Context, g Grouping, since time.Time, width time.Duration,
) ([]UsageSeries, error) {
c, ok := groupColumns[g]
if !ok {
return nil, fmt.Errorf(
"usage cannot be grouped by %q; try org, team, project or user", g)
}
if width <= 0 {
width = time.Hour
}
ms := width.Milliseconds()
// Grouped by ordinal. PostgreSQL matches a grouped expression to a selected
// one syntactically, so "(u.ts / ?) * ?" written twice is two expressions
// as far as it is concerned; the ordinal is the same one by construction,
// and both dialects accept it.
q := `
SELECT ` + c.id + `, ` + c.name + `, (u.ts / ?) * ?,
COUNT(*), SUM(u.prompt_tokens), SUM(u.completion_tokens),
SUM(u.cost_micros),
SUM(CASE WHEN u.status >= 400 THEN 1 ELSE 0 END)
FROM usage u` + c.joins + `
WHERE u.ts >= ?
GROUP BY 1, 2, 3
ORDER BY 1, 3`
rows, err := s.db.QueryContext(ctx, q, ms, ms, millis(since))
if err != nil {
return nil, err
}
defer rows.Close()
type cell struct {
name string
at map[int64]Bucket
}
found := map[string]*cell{}
var order []string
for rows.Next() {
var id, name string
var start int64
var b Bucket
if err := rows.Scan(&id, &name, &start,
&b.Requests, &b.Prompt, &b.Completion, &b.CostMicros, &b.Errors); err != nil {
return nil, err
}
b.Start = fromMillis(start)
e, ok := found[id]
if !ok {
e = &cell{name: name, at: map[int64]Bucket{}}
found[id] = e
order = append(order, id)
}
e.at[start] = b
}
if err := rows.Err(); err != nil {
return nil, err
}
first := (millis(since) / ms) * ms
last := (millis(time.Now()) / ms) * ms
out := make([]UsageSeries, 0, len(order))
for _, id := range order {
e := found[id]
u := UsageSeries{Grouping: g, ID: id, Name: e.name}
for t := first; t <= last; t += ms {
b, ok := e.at[t]
if !ok {
b = Bucket{Start: fromMillis(t)}
}
u.Buckets = append(u.Buckets, b)
u.Requests += b.Requests
u.Prompt += b.Prompt
u.Completion += b.Completion
u.CostMicros += b.CostMicros
u.Errors += b.Errors
}
out = append(out, u)
}
return out, nil
}