SPB Git

Repository Public

catalog.go 4.4 KB 102 lines go

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
Files main
Menu

Theme