Repository Public
1package main23import (4 "fmt"5 "sort"6 "strings"78 "clustr.spboucher.ai/mcc/internal/protocol"9)1011// observedDoc is the availability actually observed on real machines,12// extracted from the database after a pilot run (docs/metrics-observed.json).13type observedDoc struct {14 Runs []struct {15 Node string `json:"node"`16 Model string `json:"model"`17 OS string `json:"os"`18 Date string `json:"date"`19 Agent string `json:"agent_version"`20 Samples map[string]int64 `json:"samples"` // metric -> number of raw samples21 Declared map[string]string `json:"availability"` // metric -> declared state22 Reference string `json:"reference,omitempty"`23 } `json:"runs"`24}2526func esc(s string) string { return strings.ReplaceAll(s, "|", `\|`) }2728// catalogMarkdown renders docs/METRICS-CATALOG.md from protocol.Catalog, so29// the document cannot drift from the code.30func catalogMarkdown(obs *observedDoc) string {31 var b strings.Builder32 b.WriteString("# Metrics catalog\n\n")33 b.WriteString("<!-- GENERATED by `go run ./cmd/mcc-agent catalog --markdown --observed ../docs/metrics-observed.json`. Do not edit by hand. -->\n\n")34 b.WriteString("Source of truth: `services/internal/protocol/metrics.go` (`protocol.Catalog`). The same table seeds\n")35 b.WriteString("`metric_catalog` at ingest start-up and drives the agent collectors.\n\n")36 b.WriteString("Rules:\n\n")37 b.WriteString("- A metric that cannot be measured produces **no sample**. It is declared in the report's `availability` map as\n")38 b.WriteString(" `unsupported` (not measurable on this hardware/OS), `permission_denied` (measurable, but not with the agent's\n")39 b.WriteString(" privileges) or `unavailable` (the collector failed this round). Never an estimate, never a zero.\n")40 b.WriteString("- `counter_rate` metrics are computed by the agent from a monotonic counter: the first round after start, and any\n")41 b.WriteString(" round where the counter went backwards, produce no sample.\n")42 b.WriteString("- IDs are stable forever and never reused.\n")43 fmt.Fprintf(&b, "- Cardinality per report: ≤ %d interfaces, ≤ %d volumes, ≤ %d processes, ≤ %d services, ≤ %d samples, labels ≤ %d bytes.\n\n",44 protocol.MaxInterfaces, protocol.MaxVolumes, protocol.MaxProcesses, protocol.MaxServices, protocol.MaxSamples, protocol.MaxLabelLen)45 b.WriteString("## Catalog\n\n")46 b.WriteString("| ID | Name | Unit | Kind | Interval | Label | Description | Source | Limitations |\n|---:|---|---|---|---:|---|---|---|---|\n")47 for _, m := range protocol.Catalog {48 label := "—"49 if m.Labeled {50 label = "yes"51 }52 lim := m.Limits53 if lim == "" {54 lim = "—"55 }56 fmt.Fprintf(&b, "| %d | `%s` | %s | %s | %d s | %s | %s | %s | %s |\n", m.ID, m.Name, m.Unit, m.Kind, m.IntervalS, label, esc(m.Description), esc(m.Source), esc(lim))57 }58 b.WriteString("\n## Observed availability\n\n")59 if obs == nil || len(obs.Runs) == 0 {60 b.WriteString("No pilot run recorded.\n")61 return b.String()62 }63 b.WriteString("Status of every metric as observed on real machines (queried from the database after the run, not assumed).\n")64 b.WriteString("`measured (n)` = n raw samples stored during the run.\n\n")65 b.WriteString("| Metric |")66 for _, r := range obs.Runs {67 fmt.Fprintf(&b, " %s |", esc(r.Node))68 }69 b.WriteString("\n|---|")70 for range obs.Runs {71 b.WriteString("---|")72 }73 b.WriteString("\n")74 for _, m := range protocol.Catalog {75 fmt.Fprintf(&b, "| `%s` |", m.Name)76 for _, r := range obs.Runs {77 switch {78 case r.Samples[m.Name] > 0:79 fmt.Fprintf(&b, " measured (%d) |", r.Samples[m.Name])80 case r.Declared[m.Name] != "":81 fmt.Fprintf(&b, " %s |", r.Declared[m.Name])82 default:83 b.WriteString(" not observed |")84 }85 }86 b.WriteString("\n")87 }88 b.WriteString("\nRuns:\n\n")89 runs := obs.Runs90 sort.SliceStable(runs, func(i, j int) bool { return runs[i].Date < runs[j].Date })91 for _, r := range runs {92 fmt.Fprintf(&b, "- **%s** — %s, %s, agent %s, %s", esc(r.Node), esc(r.Model), esc(r.OS), esc(r.Agent), esc(r.Date))93 if r.Reference != "" {94 fmt.Fprintf(&b, " (%s)", esc(r.Reference))95 }96 b.WriteString("\n")97 }98 b.WriteString("\nLinux has not been run yet: its column will appear after the first Linux pilot. Expected from the code:\n")99 b.WriteString("`mem.wired`, `mem.compressed`, `mem.pressure.level`, `gpu.*`, `thermal.pressure` → `unsupported`.\n")100 return b.String()101}102