Files
llmgw/internal/web/timeseries.go
T
Ilker ManapandClaude Opus 5 07809490e3 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

255 lines
7.4 KiB
Go

package web
import (
"fmt"
"html/template"
"math"
"sort"
"strings"
"time"
"gitea.mynodes.xyz/ilker/llmgw/internal/promq"
)
// vizColours is the categorical palette, in the order it is handed out.
//
// Fixed order, never cycled. A fifth line does not get a generated hue — it is
// folded into "other" by foldSeries below, because a chart whose colours repeat
// is one where two lines mean the same thing and neither can be read.
var vizColours = []string{"--viz-1", "--viz-2", "--viz-3", "--viz-4"}
// otherColour is the muted grey the tail is drawn in, so it reads as a total
// rather than as a fifth thing with a name.
const otherColour = "--muted"
const (
tsW = 720.0
tsH = 150.0
tsPadL = 44.0
tsPadB = 18.0
tsPadT = 8.0
tsGridRows = 3
)
// TimeSeries is a chart of several lines over one clock.
type TimeSeries struct {
SVG template.HTML
Legend []LegendEntry
// Empty is true when there was nothing to draw, so the page can say why
// rather than showing a frame with no lines in it.
Empty bool
Peak string
}
// LegendEntry names one line and the colour it was drawn in.
//
// A legend is always present for two lines or more: colour alone is not an
// encoding anybody can rely on, and a reader who cannot tell two lines apart
// has a picture rather than a chart.
type LegendEntry struct {
Name string
Colour string
Last string
}
// LineChart draws several series against one axis.
//
// One axis, always. Two measures of different scale belong in two charts: a
// second y-axis lets any two lines be made to cross wherever the author likes,
// and the reader has no way to know it happened.
//
// Ranked by peak, which is what a gauge asks: the model that hit the ceiling is
// the one worth a colour. For a counter, see LineChartTotals.
func LineChart(series []promq.Series, unit string, maxSeries int) TimeSeries {
return lineChart(series, unit, maxSeries, promq.Series.Max)
}
// LineChartTotals is LineChart ranked by the sum over the window.
//
// Which is the right question of a counter. "Who used the most" is answered by
// the total, and ranking by peak would give a colour to the team that made one
// large burst over the team that ran steadily all week — the opposite of what a
// usage report is read for.
func LineChartTotals(series []promq.Series, unit string, maxSeries int) TimeSeries {
return lineChart(series, unit, maxSeries, promq.Series.Sum)
}
func lineChart(series []promq.Series, unit string, maxSeries int,
weight func(promq.Series) float64,
) TimeSeries {
if maxSeries <= 0 || maxSeries > len(vizColours) {
maxSeries = len(vizColours)
}
series = foldSeries(series, maxSeries, weight)
if len(series) == 0 {
return TimeSeries{Empty: true}
}
minT, maxT, maxV := bounds(series)
if maxT.Equal(minT) {
// One instant is not a line. Reported as empty rather than drawn as a
// dot in the corner, which reads as a broken chart.
return TimeSeries{Empty: true}
}
// A flat zero is a real answer — nothing is happening — and drawing it
// along the bottom says so, where an autoscaled empty frame would not.
if maxV <= 0 {
maxV = 1
}
maxV = niceCeiling(maxV)
var b strings.Builder
fmt.Fprintf(&b, `<svg class="chart chart-lines" viewBox="0 0 %.0f %.0f" role="img">`, tsW, tsH)
writeGrid(&b, maxV, unit)
out := TimeSeries{Peak: formatValue(maxV, unit)}
span := maxT.Sub(minT).Seconds()
for i, s := range series {
colour := otherColour
if s.Name != otherLabel {
colour = vizColours[i%len(vizColours)]
}
writeLine(&b, s, minT, span, maxV, colour)
out.Legend = append(out.Legend, LegendEntry{
Name: s.Name, Colour: colour, Last: formatValue(s.Last(), unit),
})
}
b.WriteString(`</svg>`)
out.SVG = template.HTML(b.String()) //nolint:gosec // numbers and CSS vars only
return out
}
const otherLabel = "other"
// foldSeries keeps the busiest lines and sums the rest into one.
//
// Rather than dropping the tail, which would make a chart that does not add up,
// or colouring it, which needs hues the palette does not have. The fold is
// labelled so nobody reads it as a single model.
//
// What "busiest" means is the caller's: a gauge is ranked by its peak and a
// counter by its total, and the two disagree exactly where it matters.
func foldSeries(in []promq.Series, keep int, weight func(promq.Series) float64) []promq.Series {
clean := make([]promq.Series, 0, len(in))
for _, s := range in {
if len(s.Points) > 0 {
clean = append(clean, s)
}
}
if len(clean) <= keep {
return clean
}
sort.SliceStable(clean, func(i, j int) bool { return weight(clean[i]) > weight(clean[j]) })
rest := clean[keep-1:]
folded := promq.Series{Name: otherLabel}
// Summed by timestamp, because the tail's lines do not necessarily share
// sample times and adding them by index would shift points sideways.
at := map[int64]float64{}
for _, s := range rest {
for _, p := range s.Points {
at[p.At.Unix()] += p.Value
}
}
keys := make([]int64, 0, len(at))
for k := range at {
keys = append(keys, k)
}
sort.Slice(keys, func(i, j int) bool { return keys[i] < keys[j] })
for _, k := range keys {
folded.Points = append(folded.Points, promq.Point{At: time.Unix(k, 0), Value: at[k]})
}
return append(append([]promq.Series{}, clean[:keep-1]...), folded)
}
func bounds(series []promq.Series) (minT, maxT time.Time, maxV float64) {
for _, s := range series {
for _, p := range s.Points {
if minT.IsZero() || p.At.Before(minT) {
minT = p.At
}
if p.At.After(maxT) {
maxT = p.At
}
if p.Value > maxV {
maxV = p.Value
}
}
}
return minT, maxT, maxV
}
// writeGrid draws the horizontal rules and their labels.
//
// Recessive on purpose: the grid is there to be read off, not looked at, and a
// grid as dark as the data competes with it.
func writeGrid(b *strings.Builder, maxV float64, unit string) {
plotH := tsH - tsPadB - tsPadT
for i := 0; i <= tsGridRows; i++ {
y := tsPadT + plotH*float64(i)/tsGridRows
v := maxV * float64(tsGridRows-i) / tsGridRows
fmt.Fprintf(b, `<line x1="%.0f" y1="%.1f" x2="%.0f" y2="%.1f" class="axis"/>`,
tsPadL, y, tsW, y)
fmt.Fprintf(b, `<text x="%.0f" y="%.1f" class="tick">%s</text>`,
tsPadL-6, y+3, escapeText(formatValue(v, unit)))
}
}
func writeLine(b *strings.Builder, s promq.Series, minT time.Time,
span, maxV float64, colour string,
) {
plotW := tsW - tsPadL
plotH := tsH - tsPadB - tsPadT
fmt.Fprintf(b, `<polyline class="line" fill="none" stroke="var(%s)" points="`, cssVar(colour))
for _, p := range s.Points {
x := tsPadL + plotW*(p.At.Sub(minT).Seconds()/span)
y := tsPadT + plotH*(1-clamp01(p.Value/maxV))
fmt.Fprintf(b, "%.1f,%.1f ", x, y)
}
b.WriteString(`"/>`)
}
func clamp01(v float64) float64 {
if math.IsNaN(v) || v < 0 {
return 0
}
if v > 1 {
return 1
}
return v
}
// niceCeiling rounds an axis maximum up to something a person would choose.
//
// An axis topping out at 0.8347 makes every gridline a number nobody can hold
// in their head, and the shape of the data is what the chart is for.
func niceCeiling(v float64) float64 {
if v <= 0 {
return 1
}
mag := math.Pow(10, math.Floor(math.Log10(v)))
for _, step := range []float64{1, 2, 2.5, 5, 10} {
if v <= step*mag {
return step * mag
}
}
return 10 * mag
}
func formatValue(v float64, unit string) string {
switch unit {
case "%":
return fmt.Sprintf("%.0f%%", v*100)
case "s":
if v < 1 {
return fmt.Sprintf("%.0fms", v*1000)
}
return fmt.Sprintf("%.1fs", v)
case "bytes":
return compact(v) + "B"
default:
return compact(v)
}
}