diff --git a/CHANGELOG.md b/CHANGELOG.md index 133e03e7..604af829 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,19 @@ left for an administrator, Chat, Your keys and Sign out on the right for everyone — with the current page marked. The chat and key pages name the person's project by its path rather than its id. +### The quotas page says what actually applies + +A branch that sets no limit of its own used to read "—" in every column while +its organization held it to sixty requests a minute. Each limit now shows the +value it is held to from above, muted and marked ↑, with where it comes from on +hover; a larger value set below a stricter one says what caps it, for rate and +token limits as well as budgets. Spend and budget share a column with a meter +that turns red past 90%. The tree is indented like the people page, opening a +form or saving one no longer reloads the page, and the explanations moved under +"How limits combine". Projects are placed under their team by id rather than by +the start of their path, which misplaced them when two organizations shared a +name. + ## v0.9.2 — 2026-09-28 ### A new control plane serves a model by itself diff --git a/internal/web/admin_quotas.go b/internal/web/admin_quotas.go index ebabdebf..d8484671 100644 --- a/internal/web/admin_quotas.go +++ b/internal/web/admin_quotas.go @@ -25,6 +25,11 @@ type QuotaAdmin interface { PutLimits(ctx context.Context, l store.Limits) error ClearLimits(ctx context.Context, scope store.Scope, id string) error UsageByScope(ctx context.Context, scope store.Scope, since time.Time) ([]store.ScopeUsage, error) + // Tree is the same tree with ids all the way down, so a project is placed + // under its team by id rather than by matching the start of its path — + // which put projects under the wrong team when two organizations shared a + // name. + Tree(ctx context.Context) ([]store.TreeOrg, error) } // quotaRow is one place a quota can be written, and what is written there. @@ -65,6 +70,16 @@ type quotaRow struct { // show it as though it applied, and the first sign would be a refusal that // disagrees with what is on screen. Shadowed string + + // RPMFrom, TPMFrom and BudgetFrom name the ancestor a limit comes from when + // this row sets none of its own, with the value in RPMUp, TPMUp and + // BudgetUp. A project with "—" in every column read as unlimited when its + // organization held it to sixty requests a minute. + RPMUp, TPMUp, BudgetUp string + RPMFrom, TPMFrom, BudgetFrom string + // ModelsFrom names the nearest ancestor with a model list, for a row with + // none of its own. + ModelsFrom string } type adminQuotasData struct { @@ -216,37 +231,12 @@ func (p *AccountPages) renderQuotas(w http.ResponseWriter, r *http.Request, } spend := p.spendByScope(r.Context(), s, time.Now().Add(-window)) - orgs, _ := s.AllOrgs(r.Context()) - teams, _ := s.AllTeams(r.Context()) - projects, _ := s.AllProjects(r.Context()) - - // Depth first, so a team reads as belonging to the organization above it - // rather than as another row in a flat list. - teamsByOrg := map[string][]store.TeamPath{} - for _, t := range teams { - teamsByOrg[t.OrgID] = append(teamsByOrg[t.OrgID], t) + tree, err := s.Tree(r.Context()) + if err != nil { + p.log.Error("could not read the tree", "err", err) + d.Error = "could not read the organizations" } - pathOf := map[string]string{} - for _, pr := range projects { - pathOf[pr.ID] = pr.Path - } - - for _, o := range orgs { - d.Rows = append(d.Rows, quotaRow2(store.ScopeOrg, o.ID, o.Name, o.Name, 0, limits, spend)) - for _, t := range teamsByOrg[o.ID] { - d.Rows = append(d.Rows, - quotaRow2(store.ScopeTeam, t.ID, t.Name, o.Name+" / "+t.Name, 1, limits, spend)) - for _, pr := range projects { - if !strings.HasPrefix(pathOf[pr.ID], o.Name+" / "+t.Name+" / ") { - continue - } - name := strings.TrimPrefix(pathOf[pr.ID], o.Name+" / "+t.Name+" / ") - d.Rows = append(d.Rows, - quotaRow2(store.ScopeProject, pr.ID, name, pathOf[pr.ID], 2, limits, spend)) - } - } - } - markShadowed(d.Rows, limits, orgs, teamsByOrg, projects, pathOf) + d.Rows = quotaRows(tree, limits, spend) for i := range d.Rows { d.Rows[i].Editing = d.Editing == string(d.Rows[i].Scope)+":"+d.Rows[i].ID @@ -274,73 +264,116 @@ func (p *AccountPages) spendByScope(ctx context.Context, s QuotaAdmin, return out } +// quotaRows lays the tree out depth first, each row with what it sets and +// what it is held to from above. +func quotaRows(tree []store.TreeOrg, limits map[string]store.Limits, spend map[string]int64) []quotaRow { + var rows []quotaRow + for _, o := range tree { + org := quotaRow2(store.ScopeOrg, o.ID, o.Name, o.Name, 0, limits, spend, nil) + rows = append(rows, org) + for _, t := range o.Teams { + crumb := o.Name + " / " + t.Name + team := quotaRow2(store.ScopeTeam, t.ID, t.Name, crumb, 1, limits, spend, + []ancestor{{o.Name, limits[key(store.ScopeOrg, o.ID)]}}) + rows = append(rows, team) + for _, pr := range t.Projects { + rows = append(rows, quotaRow2(store.ScopeProject, pr.ID, pr.Name, crumb+" / "+pr.Name, 2, + limits, spend, []ancestor{ + {t.Name, limits[key(store.ScopeTeam, t.ID)]}, + {o.Name, limits[key(store.ScopeOrg, o.ID)]}, + })) + } + } + } + return rows +} + +// ancestor is one level above a row, nearest first. +type ancestor struct { + name string + l store.Limits +} + +func key(scope store.Scope, id string) string { + return store.LimitOwner{Scope: scope, ID: id}.CounterKey() +} + func quotaRow2(scope store.Scope, id, name, crumb string, indent int, - limits map[string]store.Limits, spend map[string]int64, + limits map[string]store.Limits, spend map[string]int64, up []ancestor, ) quotaRow { - key := store.LimitOwner{Scope: scope, ID: id}.CounterKey() - l := limits[key] + l := limits[key(scope, id)] row := quotaRow{ Scope: scope, ID: id, Path: name, Crumb: crumb, Indent: indent, RPM: dash(l.RPM), TPM: dash(l.TPM), Budget: dashUnits(l.Budget), Period: string(l.BudgetPeriod), Models: strings.Join(l.AllowedModels, ", "), HasAny: l.RPM != nil || l.TPM != nil || l.Budget != nil || l.AllowedModels != nil, - Spend: units(spend[key]), + Spend: units(spend[key(scope, id)]), } if l.Budget != nil && *l.Budget > 0 { - row.Percent = int(spend[key] * 100 / *l.Budget) + row.Percent = int(spend[key(scope, id)] * 100 / *l.Budget) row.HasPct = true } + + // The strictest value above, and who set it. Resolution takes the most + // restrictive along the chain, so this is what applies when the row sets + // nothing, and what makes a larger value set here unreachable. + var rpm, tpm *int + var budget *int64 + var period store.Period + for _, a := range up { + if a.l.RPM != nil && (rpm == nil || *a.l.RPM < *rpm) { + rpm, row.RPMFrom = a.l.RPM, a.name + } + if a.l.TPM != nil && (tpm == nil || *a.l.TPM < *tpm) { + tpm, row.TPMFrom = a.l.TPM, a.name + } + if a.l.Budget != nil && (budget == nil || *a.l.Budget < *budget) { + budget, period, row.BudgetFrom = a.l.Budget, a.l.BudgetPeriod, a.name + } + if row.ModelsFrom == "" && a.l.AllowedModels != nil { + row.ModelsFrom = a.name + } + } + if rpm != nil { + row.RPMUp = strconv.Itoa(*rpm) + } + if tpm != nil { + row.TPMUp = strconv.Itoa(*tpm) + } + if budget != nil { + row.BudgetUp = units(*budget) + if period != "" { + row.BudgetUp += "/" + string(period) + } + } + + var capped []string + if l.RPM != nil && rpm != nil && *rpm < *l.RPM { + capped = append(capped, fmt.Sprintf("%s requests/min", row.RPMUp)) + } + if l.TPM != nil && tpm != nil && *tpm < *l.TPM { + capped = append(capped, fmt.Sprintf("%s tokens/min", row.TPMUp)) + } + if l.Budget != nil && budget != nil && *budget < *l.Budget { + capped = append(capped, "a budget of "+units(*budget)) + } + if len(capped) > 0 { + from := row.RPMFrom + if from == "" { + from = row.TPMFrom + } + if from == "" { + from = row.BudgetFrom + } + row.Shadowed = "above it, " + strings.Join(capped, " and ") + " still apply" + if from != "" && len(capped) == 1 { + row.Shadowed = fmt.Sprintf("%s caps this at %s", from, capped[0]) + } + } return row } -// markShadowed flags rows whose budget an ancestor already caps lower. -func markShadowed(rows []quotaRow, limits map[string]store.Limits, - orgs []store.Org, teamsByOrg map[string][]store.TeamPath, - projects []store.ProjectPath, pathOf map[string]string, -) { - budget := func(scope store.Scope, id string) *int64 { - return limits[store.LimitOwner{Scope: scope, ID: id}.CounterKey()].Budget - } - // Parent of each team and project, so a row can look upward. - parent := map[string]struct { - scope store.Scope - id string - name string - }{} - for _, o := range orgs { - for _, t := range teamsByOrg[o.ID] { - parent[t.ID] = struct { - scope store.Scope - id string - name string - }{store.ScopeOrg, o.ID, o.Name} - for _, pr := range projects { - if strings.HasPrefix(pathOf[pr.ID], o.Name+" / "+t.Name+" / ") { - parent[pr.ID] = struct { - scope store.Scope - id string - name string - }{store.ScopeTeam, t.ID, t.Name} - } - } - } - } - - for i := range rows { - own := budget(rows[i].Scope, rows[i].ID) - if own == nil { - continue - } - for cur := parent[rows[i].ID]; cur.id != ""; cur = parent[cur.id] { - if up := budget(cur.scope, cur.id); up != nil && *up < *own { - rows[i].Shadowed = fmt.Sprintf("%s caps this at %s", cur.name, units(*up)) - break - } - } - } -} - func optInt(v, what string) (*int, error) { if strings.TrimSpace(v) == "" { return nil, nil diff --git a/internal/web/admin_quotas_test.go b/internal/web/admin_quotas_test.go index c7d3e13a..121a15fa 100644 --- a/internal/web/admin_quotas_test.go +++ b/internal/web/admin_quotas_test.go @@ -76,6 +76,29 @@ type pricedNo struct{} func (pricedNo) AnythingPriced() bool { return false } // oneTeam is an org with a team and a project under it. +// Tree derives the tree from the flat lists the fake is given. +func (f *fakeQuotas) Tree(context.Context) ([]store.TreeOrg, error) { + var out []store.TreeOrg + for _, o := range f.orgs { + org := store.TreeOrg{ID: o.ID, Name: o.Name} + for _, t := range f.teams { + if t.OrgID != o.ID { + continue + } + team := store.TreeTeam{ID: t.ID, Name: t.Name} + for _, p := range f.projects { + if prefix := o.Name + " / " + t.Name + " / "; strings.HasPrefix(p.Path, prefix) { + team.Projects = append(team.Projects, + store.TreeProject{ID: p.ID, Name: strings.TrimPrefix(p.Path, prefix)}) + } + } + org.Teams = append(org.Teams, team) + } + out = append(out, org) + } + return out, nil +} + func oneTeam() *fakeQuotas { return &fakeQuotas{ orgs: []store.Org{{ID: "org-1", Name: "Scania"}}, @@ -291,7 +314,7 @@ func TestABranchWithNoQuotaSaysSoOnItsLink(t *testing.T) { // "change" on a branch that has nothing set would suggest there is // something to change. - if !strings.Contains(body, "set quota") { + if !strings.Contains(body, `">set`) { t.Errorf("an unlimited branch should invite setting one; got %s", body) } } @@ -326,11 +349,11 @@ func TestABudgetThatCannotBindSaysSo(t *testing.T) { // A budget is spend per period and spend comes from a price table. With no // prices the number reads as a limit, reports zero percent used, and binds // on nothing. - if !strings.Contains(body, "budget below stays at zero") { + if !strings.Contains(body, "budgets stay at zero") { t.Errorf("the page should say budgets cannot move; got %s", body) } // Said precisely: the other two limits are unaffected and still work. - if !strings.Contains(body, "Rate and token limits are unaffected") { + if !strings.Contains(body, "Rate and token limits still apply") { t.Error("the warning should not read as though no quota works") } } @@ -341,3 +364,30 @@ func TestAPricedClusterIsNotWarned(t *testing.T) { t.Error("a cluster with prices should see no warning") } } + +func TestABranchShowsTheLimitItIsHeldToFromAbove(t *testing.T) { + q := oneTeam() + q.limits[store.LimitOwner{Scope: store.ScopeOrg, ID: "org-1"}.CounterKey()] = + store.Limits{Scope: store.ScopeOrg, ScopeID: "org-1", RPM: ptrInt(60)} + body := mirrorGet(t, quotasPage(t, q, true), "/admin/quotas").Body.String() + + // The project sets nothing, and read "—" — which looked unlimited while + // its organization held it to sixty a minute. + if n := strings.Count(body, `60 ↑`); n != 2 { + t.Errorf("the team and the project should both show the organization's 60; found %d", n) + } +} + +func TestALargerLimitBelowSaysItIsCapped(t *testing.T) { + q := oneTeam() + q.limits[store.LimitOwner{Scope: store.ScopeOrg, ID: "org-1"}.CounterKey()] = + store.Limits{Scope: store.ScopeOrg, ScopeID: "org-1", RPM: ptrInt(60)} + q.limits[store.LimitOwner{Scope: store.ScopeProject, ID: "proj-1"}.CounterKey()] = + store.Limits{Scope: store.ScopeProject, ScopeID: "proj-1", RPM: ptrInt(500)} + body := mirrorGet(t, quotasPage(t, q, true), "/admin/quotas").Body.String() + if !strings.Contains(body, "Scania caps this at 60 requests/min") { + t.Error("a limit that can never be reached should say what holds it") + } +} + +func ptrInt(v int) *int { return &v } diff --git a/internal/web/static/base.css b/internal/web/static/base.css index 02f45ef7..7ff5209d 100644 --- a/internal/web/static/base.css +++ b/internal/web/static/base.css @@ -396,3 +396,37 @@ form.narrow, .narrow-form form { max-width: 30rem; } .capacity-cpu { display: flex; flex-wrap: wrap; gap: .4rem 1.6rem; margin: .2rem 0 1rem; } .capacity-cpu b { font-size: 1.15rem; font-variant-numeric: tabular-nums; } .capacity-cpu span { color: var(--muted); font-size: .85rem; } + +/* Quotas: the tenancy tree as a table. Depth is indentation and a guide line, + organizations are tinted, and a limit held from above is muted and arrowed. */ +table.quota-tree td { vertical-align: top; } +table.quota-tree .q-where { padding-left: .8rem; } +table.quota-tree tr.q-depth-1 .q-where { padding-left: 2rem; } +table.quota-tree tr.q-depth-2 .q-where { padding-left: 3.2rem; } +table.quota-tree tr.q-depth-0 > td { background: color-mix(in srgb, var(--accent) 5%, var(--card)); } +table.quota-tree tr.q-depth-0 .q-name { font-weight: 600; } +.q-kind { font-size: .72rem; color: var(--muted); text-transform: uppercase; letter-spacing: .04em; margin-left: .3rem; } +.q-sub { font-size: .78rem; color: var(--muted); margin-top: .15rem; } +.q-warn { color: var(--warn); } +.q-up { color: var(--muted); font-style: italic; cursor: help; } +.q-none { color: var(--line); } +.q-per { color: var(--muted); font-size: .8em; } +.q-spent { white-space: nowrap; } +.q-spend { font-variant-numeric: tabular-nums; display: inline-block; min-width: 3.5rem; text-align: right; } +.q-meter { display: inline-block; width: 5rem; height: .45rem; background: var(--line); border-radius: 3px; + margin: 0 .4rem 0 .6rem; vertical-align: middle; overflow: hidden; } +.q-meter i { display: block; height: 100%; background: var(--accent); } +.q-meter.hot i { background: var(--bad); } +.q-pct { font-size: .78rem; color: var(--muted); } +.q-act { text-align: right; white-space: nowrap; } +.q-form { max-width: 46rem; } +.q-form .field-row { align-items: flex-end; } +.q-form .field-row label { flex: 1 1 8rem; } +.q-form .field-row label.q-period { flex: 0 0 auto; } +.q-form-title { margin: .2rem 0 .4rem; font-size: .88rem; } +.q-form-actions { display: flex; gap: 1rem; align-items: center; margin-top: .6rem; } +.q-form-actions .danger { margin-left: auto; } +.q-legend { font-size: .8rem; color: var(--muted); margin: .5rem 0 0; } +details.explain { margin-top: 1.5rem; font-size: .88rem; color: var(--muted); } +details.explain > summary { cursor: pointer; color: var(--accent); } +details.explain p { max-width: 48rem; } diff --git a/internal/web/templates/admin_quotas.html b/internal/web/templates/admin_quotas.html index 481cf170..f3753ee2 100644 --- a/internal/web/templates/admin_quotas.html +++ b/internal/web/templates/admin_quotas.html @@ -2,6 +2,10 @@ Quotas · llmgw +{{/* Links and forms work as plain navigation; htmx, when it loads, swaps only + #quotas so opening a form or saving one does not jump the page. */}} + +

Quotas

@@ -9,68 +13,73 @@ {{template "nav" .Nav}}
+
+ {{if not .BudgetsBind}} {{/* A budget is spend per period and spend comes from a price table. With no prices every request costs nothing, so these numbers read as limits and bind on nothing. Self-hosted models having no per-token price is ordinary; showing somebody a budget without saying so is not. */}} - + {{end}} -{{if .Error}}

{{.Error}}

{{end}} -{{if .Message}}

{{.Message}}

{{end}} +{{if .Error}}{{end}} +{{if .Message}}

{{.Message}}

{{end}} {{if .Rows}} {{/* The tree is the interface. A quota belongs to a branch, so the form to set one opens on that branch rather than asking somebody to name it again in a box at the bottom. */}} - - +
WhereRPMTPMBudgetSpentUsed
+ + {{range .Rows}} - - + - - - - - - + + + + -{{if .Shadowed}} -{{/* A value that is written here and never reached. Resolution takes the most - restrictive along the chain, so without saying so the page would show a - number as though it applied and the first sign would be a refusal that - disagrees with the screen. */}} - -{{end}} -{{if .Models}}{{end}} {{if .Editing}} - {{end}} {{end}}
WhereRequests/minTokens/minBudgetSpent
- {{if eq .Indent 0}}{{.Path}}{{else}}{{.Path}}{{end}} - {{.Scope}} +
+ {{.Path}} {{.Scope}} + {{if .Models}}
only {{.Models}}
+ {{else if .ModelsFrom}}
models limited by {{.ModelsFrom}}
{{end}} + {{if .Shadowed}} + {{/* A value that is written here and never reached. Resolution takes the + most restrictive along the chain, so without saying so the page would + show a number as though it applied. */}} +
{{.Shadowed}}
{{end}}
{{if .RPM}}{{.RPM}}{{else}}—{{end}}{{if .TPM}}{{.TPM}}{{else}}—{{end}}{{if .Budget}}{{.Budget}}{{if .Period}}/{{.Period}}{{end}}{{else}}—{{end}}{{.Spend}}{{if .HasPct}}{{.Percent}}%{{else}}—{{end}} + {{template "quota-value" dict "Own" .RPM "Up" .RPMUp "From" .RPMFrom}}{{template "quota-value" dict "Own" .TPM "Up" .TPMUp "From" .TPMFrom}}{{if .Budget}}{{.Budget}}{{if .Period}}/{{.Period}}{{end}} + {{else}}{{template "quota-value" dict "Own" "" "Up" .BudgetUp "From" .BudgetFrom}}{{end}} + {{.Spend}} + {{if .HasPct}} + {{.Percent}}%{{end}} + {{if .Editing}}close - {{else}}{{if .HasAny}}change{{else}}set quota{{end}}{{end}} + {{else}}{{if .HasAny}}change{{else}}set{{end}}{{end}}
written here, but {{.Shadowed}}
only: {{.Models}}
-
+
+ -

Quota for {{.Crumb}} — shared by everything - beneath it. Whatever is set here replaces what was there; a field left blank - is no limit of that kind, not a limit of zero.

+

Quota for {{.Crumb}}, shared by everything beneath it. + A blank field means no limit of that kind, not a limit of zero.

+ + - + - - +
+ + Cancel + +
+

60 ↑ is held by a limit set higher +up — hover it to see where. A value set here is in normal type.

{{else}}

Nothing to give a quota to yet. Make an organization on the people page first.

{{end}} -

Limits compose downward by taking the most restrictive value, so -a team cannot raise what its organization set and a project cannot raise its -team's. Only an organization's own limit is bounded by nothing. Model lists -intersect rather than add: a project cannot allow a model its team withheld.

- -

Still not here, deliberately: per-key limits. A key is issued by -the person who owns it and bounded by the project it belongs to, and letting an -admin session reach individual keys would put every caller's throughput one -click away — llmgw keys limits --scope key for that.

+
+ How limits combine +

Along a branch the most restrictive value wins, so a team cannot raise what + its organization set and a project cannot raise its team's. Only an + organization's own limit is bounded by nothing. Model lists intersect: a + project cannot allow a model its team withheld.

+

Per-key limits are not set here: a key is bounded by its project, and + putting every caller's throughput one click from an admin session is more + than this page should do — llmgw keys limits --scope key.

+
+
{{end}} + +{{/* A limit as the table shows it: the row's own value, else the one it is + held to from above, marked as inherited and saying from where. */}} +{{define "quota-value"}}{{if .Own}}{{.Own}}{{else if .Up}}{{.Up}} ↑{{else}}—{{end}}{{end}}