Show what a group spent, and fix the reports that never ran on PostgreSQL

Quotas can be written on an organization, a team or a project, and nothing
could show what any of them had used: usage came back per key, per user and per
model only. A quota whose consumption cannot be seen is one nobody reviews
until the day it refuses somebody — and since the previous commit made a group
quota a shared pool, it is now a number several people are spending against
without being able to look at it.

`llmgw ctl usage --by team` sums every key beneath each group, with the budget
that level sets beside it.

Beside it, and only when that level sets one. A team bounded by its
organization's budget has none of its own, and printing the organization's
against each of its teams would read as though each had that much — the exact
misreading this work exists to remove.

Joined through api_keys rather than read from usage.project_id: that column
records where the key was when the request was served, while the quota is
written against the tree. They agree until a key is moved, and a report that
disagrees with the limit shown beside it is the useless one.

Three existing reports were fixed on the way, all failing on PostgreSQL and all
passing in tests, because the tests run on SQLite:

  column "k.name" must appear in the GROUP BY clause    (UsageSince)
  column "us.email" must appear in the GROUP BY clause  (UsageByUser)
  column "usage.ts" must appear in the GROUP BY clause  (UsageBuckets)

SQLite picks an arbitrary row for an ungrouped column and carries on; PostgreSQL
refuses. The first two were selecting names they had not grouped. The third
grouped "ts / ?" while selecting "(ts / ?) * ?", which PostgreSQL matches as
text and so saw a bare ts — it is grouped by ordinal now, the same expression by
construction. The dashboard's usage charts have been empty on the cluster this
whole time, with the reason only in the log.

All four queries were run against the cluster's own PostgreSQL before this was
committed, because passing on SQLite is what they were already doing.

The grouping level picks from a fixed table of levels rather than being
interpolated, so an unknown one is an error and not a fragment of SQL.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5 committed 2026-09-27 12:26:14 +02:00
1 parent ebce41e22d
commit a83493bddb
7 files changed
+524

No files matched your search

+76
View File
@@ -27,6 +27,7 @@ import (
type API struct {
models Models
capacity Capacity
usage Usage
ctl *control.Controller
}
@@ -44,6 +45,7 @@ func (a *API) Register(mux *http.ServeMux) {
mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel)
mux.HandleFunc("PUT /api/v1/models/{name}/capacity", a.putCapacity)
mux.HandleFunc("GET /api/v1/capacity", a.listCapacity)
mux.HandleFunc("GET /api/v1/usage", a.usageByScope)
mux.HandleFunc("GET /api/v1/nodes", a.listNodes)
mux.HandleFunc("GET /api/v1/models", a.listModels)
mux.HandleFunc("GET /api/v1/replicas", a.listReplicas)
@@ -314,6 +316,80 @@ type Models interface {
Scale(ctx context.Context, name string, s catalog.Scaling, by string) (catalog.Model, error)
}
// Usage reports what each group of the tenancy tree spent. The store
// implements it.
type Usage interface {
UsageByScope(ctx context.Context, scope store.Scope, since time.Time) ([]store.ScopeUsage, error)
}
// SetUsage supplies the usage reporting source.
func (a *API) SetUsage(u Usage) { a.usage = u }
// ScopeUsageView is one group's spend, with its quota when it has one.
type ScopeUsageView struct {
Scope string `json:"scope"`
ID string `json:"id"`
Name string `json:"name"`
Keys int64 `json:"keys"`
Requests int64 `json:"requests"`
Prompt int64 `json:"prompt_tokens"`
Completion int64 `json:"completion_tokens"`
CostMicros int64 `json:"cost_micros"`
Errors int64 `json:"errors"`
LastAt time.Time `json:"last_at,omitzero"`
// Budget is what this level sets, absent when it sets none. A group bounded
// only by its parent has no budget of its own, and reporting the parent's
// against each child would read as though each had that much.
Budget *int64 `json:"budget_micros,omitempty"`
BudgetPeriod string `json:"budget_period,omitempty"`
// Fraction is spend over budget, absent for the same reason.
Fraction *float64 `json:"fraction,omitempty"`
}
func (a *API) usageByScope(w http.ResponseWriter, r *http.Request) {
if a.usage == nil {
writeError(w, http.StatusNotImplemented, "this control plane has no store, so nothing is recorded")
return
}
scope := store.Scope(r.URL.Query().Get("by"))
if scope == "" {
scope = store.ScopeTeam
}
since := 24 * time.Hour
if v := r.URL.Query().Get("since"); v != "" {
d, err := time.ParseDuration(v)
if err != nil || d <= 0 {
writeError(w, http.StatusBadRequest, "since must be a positive duration, like 24h")
return
}
since = d
}
rows, err := a.usage.UsageByScope(r.Context(), scope, time.Now().Add(-since))
if err != nil {
// The only failure a caller can act on is naming a level that is not
// one, which is what this mostly is.
writeError(w, http.StatusBadRequest, err.Error())
return
}
out := make([]ScopeUsageView, 0, len(rows))
for _, u := range rows {
v := ScopeUsageView{
Scope: string(u.Scope), ID: u.ID, Name: u.Name,
Keys: u.Keys, Requests: u.Requests, Prompt: u.Prompt,
Completion: u.Completion, CostMicros: u.CostMicros, Errors: u.Errors,
LastAt: u.LastAt, Budget: u.Budget, BudgetPeriod: string(u.BudgetPeriod),
}
if f, ok := u.Spent(); ok {
v.Fraction = &f
}
out = append(out, v)
}
writeJSON(w, http.StatusOK, out)
}
// Capacity is where measured capacity is kept. The store implements it.
type Capacity interface {
PutCapacity(ctx context.Context, c store.StoredCapacity) error