` +
From ae5b4fa8f2e2e5f415e42690118bbd32e901a382 Mon Sep 17 00:00:00 2001
From: Douglas Adolph <116844282+dcadolph@users.noreply.github.com>
Date: Sat, 31 Oct 2026 06:24:00 -0500
Subject: [PATCH 04/13] Keep nodes_with_usage from restating the metrics node
count
---
internal/report/fields.go | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/internal/report/fields.go b/internal/report/fields.go
index 6c70565..0a5673f 100644
--- a/internal/report/fields.go
+++ b/internal/report/fields.go
@@ -78,6 +78,11 @@ var fieldSpecs = []fieldSpec{
Polarity: UpIsBad,
Trend: true,
},
+ {FieldRef: ref("metrics", "node_count")},
+ {
+ FieldRef: ref("metrics", "nodes_with_usage"),
+ RedundantWith: []FieldRef{ref("metrics", "node_count")},
+ },
{
FieldRef: ref("node-health", "unhealthy_nodes"),
From cbb048622ccd6cf6a2ec4f6ada2a3b7777fdf441 Mon Sep 17 00:00:00 2001
From: Douglas Adolph <116844282+dcadolph@users.noreply.github.com>
Date: Sat, 31 Oct 2026 07:05:03 -0500
Subject: [PATCH 05/13] Grade the fleet only when scanners observed enough of
it
---
docs/concepts/fleet-score.md | 37 ++++++
internal/report/brief.go | 31 +++--
internal/report/brief_test.go | 76 +++++++++++-
internal/report/score.go | 184 +++++++++++++++++++++++++--
internal/report/score_test.go | 228 ++++++++++++++++++++++++++++++++--
5 files changed, 528 insertions(+), 28 deletions(-)
diff --git a/docs/concepts/fleet-score.md b/docs/concepts/fleet-score.md
index 72e96b0..34eab4b 100644
--- a/docs/concepts/fleet-score.md
+++ b/docs/concepts/fleet-score.md
@@ -38,6 +38,35 @@ with every rule and cluster it charged and what each cap forgave, is
The exact weights live in `internal/report/score.go` and are documented
inline.
+## Coverage gate
+
+A score is only graded when enough of the fleet was observed to back it.
+Every report counts its scanner runs: one expected run per listed cluster
+for every scanner that ran on at least one cluster. A run is observed when
+it finished OK or found its feature not served (unavailable), partial when
+it was degraded, and blind when it errored or never ran on that cluster.
+
+The score is graded when both hold:
+
+- Every listed cluster has at least one observed run.
+- At least 80 percent of expected runs are observed. The floor is the
+ constant `minCoverageFraction` in `internal/report/score.go`.
+
+An ungraded score has `graded: false` and an empty `grade`. Its headline
+leads with the gap and labels the number, for example "Not enough data: 6
+of 6 scanner runs did not observe the fleet, and 2 of 2 clusters had no
+complete scanner run. Observed-only score 100." The number is still
+computed from what was observed, so it is there for inspection, but it is
+not the fleet's health. The brief leads with the same sentence.
+
+A graded score with blind or partial runs names them after the band, and
+its top band reads "nothing flagged in what was observed" in place of "no
+meaningful drift", because a blind run cannot vouch for anything. A fully
+observed fleet reads exactly as before.
+
+The counts travel in `coverage`: `expected_runs`, `observed_runs`,
+`blind_runs`, `blind_clusters`, and `fraction` (observed over expected).
+
## Cluster score
Each cluster also gets a 0-100 score on the same scale. It charges the
@@ -49,6 +78,12 @@ once in the Fleet Score. This is the same rule that sets cluster status, so
a cluster that reads healthy never loses points to a critical or warning
finding.
+A cluster with any blind scanner run (errored, or never run on it) that no
+finding made degraded or critical reads `unknown` instead of `healthy`. Its
+cluster score pays the degraded status cost, and its headline reads
+"Unknown. N scanner runs did not observe this cluster." The Fleet Score
+does not charge unknown clusters. The coverage gate covers them instead.
+
## Provenance
A score never travels alone. Every surface that reports it (the report
@@ -60,6 +95,8 @@ metadata, and the Prometheus and OpenTelemetry metrics) also carries:
one cluster.
- `excluded_clusters`: scanned clusters that produced no usable data and
were left out of the statistical population.
+- `coverage`: the scanner runs behind the score and how many observed the
+ fleet (see [Coverage gate](#coverage-gate)).
A score computed across six clusters and one computed across sixty are
different claims. The provenance says which one you are reading.
diff --git a/internal/report/brief.go b/internal/report/brief.go
index 25b62c2..5780ba2 100644
--- a/internal/report/brief.go
+++ b/internal/report/brief.go
@@ -19,28 +19,38 @@ type Brief struct {
// generateBrief synthesizes an executive summary from a fully built report: the
// score, the worst incident, cohort drift, degraded coverage, and the fixes
-// that matter most.
+// that matter most. An ungraded score leads with the coverage sentence and
+// labels the score observed-only on the next line.
func generateBrief(r *Report) Brief {
crit := countFindingsBySeverity(r.Findings, SeverityCritical)
warn := countFindingsBySeverity(r.Findings, SeverityWarning)
+ fs := r.FleetScore
+ coverage := coverageSentence(fs.Coverage, len(r.Clusters))
- b := Brief{
- Headline: fmt.Sprintf(
+ var b Brief
+ if fs.Graded {
+ b.Headline = fmt.Sprintf(
"Fleet score %d (%s) from %d clusters across %d dimensions. "+
"%d critical and %d warning findings across %d incidents.",
- r.FleetScore.Score, r.FleetScore.Grade, r.FleetScore.SampleSize,
- r.FleetScore.Dimensions, crit, warn, len(r.Incidents),
- ),
+ fs.Score, fs.Grade, fs.SampleSize, fs.Dimensions, crit, warn, len(r.Incidents),
+ )
+ } else {
+ b.Headline = "Not enough data: " + coverage
+ b.Lines = append(b.Lines, fmt.Sprintf(
+ "Observed-only score %d from %d clusters across %d dimensions. "+
+ "%d critical and %d warning findings across %d incidents.",
+ fs.Score, fs.SampleSize, fs.Dimensions, crit, warn, len(r.Incidents),
+ ))
}
if line := normLine(r.Findings); line != "" {
b.Lines = append(b.Lines, line)
}
- if r.FleetScore.ExcludedClusters > 0 {
+ if fs.Graded && fs.ExcludedClusters > 0 {
b.Lines = append(b.Lines, fmt.Sprintf(
"%d cluster(s) excluded from the score for insufficient data.",
- r.FleetScore.ExcludedClusters,
+ fs.ExcludedClusters,
))
}
@@ -58,7 +68,10 @@ func generateBrief(r *Report) Brief {
b.Lines = append(b.Lines, fmt.Sprintf("%d cluster metric(s) drifted from their cohort baseline.", cohortOutliers))
}
- if len(r.Degraded) > 0 {
+ switch {
+ case fs.Graded && coverage != "":
+ b.Lines = append(b.Lines, coverage)
+ case fs.Graded && len(r.Degraded) > 0:
b.Lines = append(b.Lines, fmt.Sprintf(
"Coverage is partial: %d scanner run(s) degraded on %d cluster(s).",
len(r.Degraded), len(r.DegradedByCluster()),
diff --git a/internal/report/brief_test.go b/internal/report/brief_test.go
index 3402dc2..3cbe71c 100644
--- a/internal/report/brief_test.go
+++ b/internal/report/brief_test.go
@@ -1,8 +1,13 @@
package report
import (
+ "fmt"
"strings"
"testing"
+
+ "github.com/google/go-cmp/cmp"
+
+ "github.com/dcadolph/fleetsweeper/internal/scanner"
)
// TestGenerateBrief verifies the executive summary reflects the report's score,
@@ -13,7 +18,7 @@ func TestGenerateBrief(t *testing.T) {
r := &Report{
Clusters: []string{"a", "b", "c"},
FleetScore: FleetScore{
- Score: 73, Grade: "C", SampleSize: 3, Dimensions: 24, ExcludedClusters: 1,
+ Score: 73, Grade: "C", Graded: true, SampleSize: 3, Dimensions: 24, ExcludedClusters: 1,
},
Findings: []Finding{
{Title: "a webhook down", Severity: SeverityCritical, Cluster: "a", Scanner: "admission",
@@ -60,3 +65,72 @@ func TestGenerateBrief(t *testing.T) {
t.Errorf("fix line missing remediation command:\n%s", joined)
}
}
+
+// TestGenerateBriefCoverage verifies the brief leads with coverage when the score is not graded
+// and names blind runs when it is.
+func TestGenerateBriefCoverage(t *testing.T) {
+ t.Parallel()
+ clusters := []string{"c1", "c2"}
+ allErrored := map[runKey]*scanner.Result{}
+ for _, c := range clusters {
+ for _, s := range []string{"s1", "s2", "s3"} {
+ allErrored[runKey{scanner: s, cluster: c}] = runOf(erroredRun(s))
+ }
+ }
+ tests := []struct {
+ Name string
+ Override map[runKey]*scanner.Result
+ WantHeadline string
+ WantFirst string
+ WantLine string
+ WantNoLine string
+ }{{ // Test 0: Every run errored, so the coverage sentence is the first line.
+ Name: "all errored",
+ Override: allErrored,
+ WantHeadline: "Not enough data: 6 of 6 scanner runs did not observe the fleet, " +
+ "and 2 of 2 clusters had no complete scanner run.",
+ WantFirst: "Observed-only score 100",
+ WantNoLine: "Coverage is partial",
+ }, { // Test 1: One blind run on a graded fleet adds the coverage sentence to the lines.
+ Name: "graded with a blind run",
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: runOf(erroredRun("s1")),
+ },
+ WantHeadline: "Fleet score 100 (A)",
+ WantLine: "1 of 6 scanner runs did not observe the fleet.",
+ WantNoLine: "Coverage is partial",
+ }, { // Test 2: A fully observed fleet carries no coverage sentence.
+ Name: "fully observed",
+ WantHeadline: "Fleet score 100 (A)",
+ WantNoLine: "scanner runs",
+ }}
+ for testNum, test := range tests {
+ t.Run(fmt.Sprintf("test %d: %s", testNum, test.Name), func(t *testing.T) {
+ t.Parallel()
+ r := Build(clusters, coverageResults(clusters, 3, test.Override))
+ b := r.Brief
+ if !strings.HasPrefix(b.Headline, test.WantHeadline) {
+ t.Errorf("brief headline %q, want prefix %q", b.Headline, test.WantHeadline)
+ }
+ if test.WantFirst != "" {
+ if len(b.Lines) == 0 {
+ t.Fatalf("brief has no lines, want first %q", test.WantFirst)
+ }
+ if !strings.HasPrefix(b.Lines[0], test.WantFirst) {
+ t.Errorf("first line %q, want prefix %q", b.Lines[0], test.WantFirst)
+ }
+ }
+ joined := strings.Join(b.Lines, "\n")
+ if test.WantLine != "" && !strings.Contains(joined, test.WantLine) {
+ t.Errorf("brief lines missing %q:\n%s", test.WantLine, joined)
+ }
+ if test.WantNoLine != "" && strings.Contains(joined, test.WantNoLine) {
+ t.Errorf("brief lines carry %q:\n%s", test.WantNoLine, joined)
+ }
+ gradedHead := !strings.HasPrefix(b.Headline, "Not enough data")
+ if diff := cmp.Diff(r.FleetScore.Graded, gradedHead); diff != "" {
+ t.Errorf("brief headline disagrees with Graded (-want +got):\n%s", diff)
+ }
+ })
+ }
+}
diff --git a/internal/report/score.go b/internal/report/score.go
index 063f1fb..1516489 100644
--- a/internal/report/score.go
+++ b/internal/report/score.go
@@ -3,7 +3,9 @@ package report
import (
"fmt"
"math"
+ "sort"
+ "github.com/dcadolph/fleetsweeper/internal/scanner"
"github.com/dcadolph/fleetsweeper/internal/util"
)
@@ -12,12 +14,21 @@ import (
// asymmetric: clusters in trouble pull it down faster than warnings do, and
// individual findings are capped so a noisy fleet does not collapse to zero on
// volume alone. The Drivers list names the top reasons the score sits where it
-// does so operators can read the number and the explanation in one glance.
+// does so operators can read the number and the explanation in one glance. A
+// score resting on too little observed data is not graded: Graded is false, Grade
+// is empty, and the headline says how much of the fleet went unobserved.
type FleetScore struct {
- // Score is the rounded 0-100 health score.
+ // Score is the rounded 0-100 health score. When Graded is false it is computed from the
+ // observed data only and must not be read as the fleet's health.
Score int `json:"score"`
- // Grade is a single-letter rollup of Score: A 90+, B 80+, C 70+, D 60+, F under 60.
+ // Grade is a single-letter rollup of Score: A 90+, B 80+, C 70+, D 60+, F under 60. Empty
+ // when Graded is false.
Grade string `json:"grade"`
+ // Graded is true when coverage clears the floor: every listed cluster has at least one
+ // observed scanner run, and at least minCoverageFraction of expected runs are observed.
+ Graded bool `json:"graded"`
+ // Coverage counts the scanner runs behind the score.
+ Coverage FleetCoverage `json:"coverage"`
// Headline is a one-line plain-English summary suitable for a hero card.
Headline string `json:"headline"`
// Drivers names the top three factors pulling the score below 100, in
@@ -35,6 +46,26 @@ type FleetScore struct {
ExcludedClusters int `json:"excluded_clusters"`
}
+// FleetCoverage counts how many of the scanner runs a report expected actually observed the
+// fleet. A run is observed when its state is OK or unavailable, partial when degraded, and blind
+// when it errored or never ran on the cluster.
+type FleetCoverage struct {
+ // ExpectedRuns is the listed clusters times the scanners that ran on at least one cluster.
+ ExpectedRuns int `json:"expected_runs"`
+ // ObservedRuns is how many expected runs finished OK or found the feature unavailable.
+ ObservedRuns int `json:"observed_runs"`
+ // BlindRuns is how many expected runs errored or never ran on their cluster.
+ BlindRuns int `json:"blind_runs"`
+ // BlindClusters is how many listed clusters have no observed run.
+ BlindClusters int `json:"blind_clusters"`
+ // Fraction is ObservedRuns over ExpectedRuns, zero when no run was expected.
+ Fraction float64 `json:"fraction"`
+}
+
+// minCoverageFraction is the share of expected scanner runs that must be observed before the
+// fleet score is graded.
+const minCoverageFraction = 0.8
+
// FleetScoreDriver describes a single factor reducing the fleet score.
type FleetScoreDriver struct {
// Reason is a short human-readable label.
@@ -80,22 +111,134 @@ func Rescore(r *Report) {
// floored at zero, and the drivers are the ledger's top three terms.
func scoreWithAttribution(r *Report) (FleetScore, ScoreAttribution) {
if r == nil {
- return FleetScore{Score: 100, Grade: "A", Headline: "No data yet."}, ScoreAttribution{}
+ return FleetScore{Score: 100, Headline: "No data yet."}, ScoreAttribution{}
}
a := computeScoreAttribution(r)
raw := math.Max(100.0-a.Total, 0)
score := int(math.Round(raw))
sample, dims, excluded := scoreProvenance(r)
- return FleetScore{
+ cov := fleetCoverage(r)
+ fs := FleetScore{
Score: score,
- Grade: grade(score),
- Headline: headline(score, r),
+ Graded: cov.clearsFloor(),
+ Coverage: cov,
Drivers: a.Drivers(),
SampleSize: sample,
Dimensions: dims,
ExcludedClusters: excluded,
- }, a
+ }
+ if fs.Graded {
+ fs.Grade = grade(score)
+ }
+ fs.Headline = headline(fs, len(r.Clusters))
+ return fs, a
+}
+
+// fleetCoverage counts r's expected, observed, and blind scanner runs from the run-state
+// table.
+func fleetCoverage(r *Report) FleetCoverage {
+ scanners := expectedScanners(r)
+ var c FleetCoverage
+ for _, cluster := range r.Clusters {
+ observed, blind := clusterRunCounts(r, cluster, scanners)
+ c.ExpectedRuns += len(scanners)
+ c.ObservedRuns += observed
+ c.BlindRuns += blind
+ if observed == 0 {
+ c.BlindClusters++
+ }
+ }
+ if c.ExpectedRuns > 0 {
+ c.Fraction = float64(c.ObservedRuns) / float64(c.ExpectedRuns)
+ }
+ return c
+}
+
+// expectedScanners returns every scanner with a section or a degraded entry in r, so a
+// scanner that errored on every cluster is still expected everywhere.
+func expectedScanners(r *Report) []string {
+ seen := make(map[string]struct{}, len(r.Sections))
+ for name := range r.Sections {
+ seen[name] = struct{}{}
+ }
+ for _, d := range r.Degraded {
+ seen[d.Scanner] = struct{}{}
+ }
+ names := make([]string, 0, len(seen))
+ for name := range seen {
+ names = append(names, name)
+ }
+ sort.Strings(names)
+ return names
+}
+
+// clusterRunCounts returns how many of scanners' runs on cluster observed it (OK or
+// unavailable) and how many were blind (errored or never ran). Degraded runs are neither.
+func clusterRunCounts(r *Report, cluster string, scanners []string) (observed, blind int) {
+ for _, name := range scanners {
+ st, ok := runState(r, name, cluster)
+ switch {
+ case !ok || st == scanner.StateErrored:
+ blind++
+ case st == scanner.StateOK || st == scanner.StateUnavailable:
+ observed++
+ }
+ }
+ return observed, blind
+}
+
+// clearsFloor reports whether c is enough coverage to grade: no listed cluster went unobserved
+// and the observed share is at least minCoverageFraction. A report that expected no runs and
+// lists no clusters has nothing missing and clears it.
+func (c FleetCoverage) clearsFloor() bool {
+ if c.BlindClusters > 0 {
+ return false
+ }
+ return c.ExpectedRuns == 0 || c.Fraction >= minCoverageFraction
+}
+
+// partialRuns returns how many expected runs were degraded: neither observed nor blind.
+func (c FleetCoverage) partialRuns() int {
+ return c.ExpectedRuns - c.ObservedRuns - c.BlindRuns
+}
+
+// coverageSentence describes the runs that did not fully observe a fleet of clusters, such as
+// "3 of 40 scanner runs did not observe the fleet." It returns "" when every run was observed.
+func coverageSentence(c FleetCoverage, clusters int) string {
+ partial := c.partialRuns()
+ var s string
+ switch {
+ case c.ExpectedRuns == 0 && c.BlindClusters == 0:
+ return ""
+ case c.ExpectedRuns == 0:
+ return fmt.Sprintf("No scanner ran on %d listed cluster%s.",
+ c.BlindClusters, util.Plural(c.BlindClusters))
+ case c.BlindRuns > 0 && partial > 0:
+ s = fmt.Sprintf("%d of %d scanner runs did not observe the fleet and %d %s partial",
+ c.BlindRuns, c.ExpectedRuns, partial, wasWere(partial))
+ case c.BlindRuns > 0:
+ s = fmt.Sprintf("%d of %d scanner runs did not observe the fleet",
+ c.BlindRuns, c.ExpectedRuns)
+ case partial > 0:
+ s = fmt.Sprintf("%d of %d scanner runs %s partial",
+ partial, c.ExpectedRuns, wasWere(partial))
+ default:
+ return ""
+ }
+ if c.BlindClusters > 0 {
+ s += fmt.Sprintf(", and %d of %d cluster%s had no complete scanner run",
+ c.BlindClusters, clusters, util.Plural(clusters))
+ }
+ return s + "."
+}
+
+// wasWere returns the past tense of "to be" agreeing with n.
+func wasWere(n int) string {
+ if n == 1 {
+ return "was"
+ }
+ return "were"
}
// scoreProvenance derives the sample size, contributing dimension count, and
@@ -139,10 +282,29 @@ func grade(score int) string {
}
// headline returns a one-line plain-English summary suitable for the hero
-// card on the dashboard.
-func headline(score int, r *Report) string {
- clusters := len(r.Clusters)
+// card on the dashboard. An ungraded score leads with the missing coverage and
+// labels the number observed-only. A graded score with unobserved runs names them
+// after the band and never claims the fleet is free of drift.
+func headline(fs FleetScore, clusters int) string {
+ cov := coverageSentence(fs.Coverage, clusters)
+ if !fs.Graded {
+ return fmt.Sprintf("Not enough data: %s Observed-only score %d.", cov, fs.Score)
+ }
+ band := scoreBand(fs.Score, clusters, cov != "")
+ if cov == "" {
+ return band
+ }
+ return band + " " + cov
+}
+
+// scoreBand returns the headline for a graded score of a fleet of clusters. When some runs
+// went unobserved the top band says nothing was flagged in what was observed rather than
+// claiming no drift.
+func scoreBand(score, clusters int, unobserved bool) string {
switch {
+ case score >= 95 && unobserved:
+ return fmt.Sprintf("%d cluster%s, nothing flagged in what was observed.",
+ clusters, util.Plural(clusters))
case score >= 95:
return fmt.Sprintf("%d cluster%s, no meaningful drift.", clusters, util.Plural(clusters))
case score >= 85:
diff --git a/internal/report/score_test.go b/internal/report/score_test.go
index 034cb04..647a5fe 100644
--- a/internal/report/score_test.go
+++ b/internal/report/score_test.go
@@ -1,13 +1,28 @@
package report
import (
+ "encoding/json"
"fmt"
+ "strings"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/google/go-cmp/cmp/cmpopts"
+
+ "github.com/dcadolph/fleetsweeper/internal/scanner"
)
+// observedBy returns sections in which one OK scanner observed every named cluster, so a
+// hand-built report clears the coverage gate.
+func observedBy(clusters ...string) map[string]*SectionReport {
+ per := make(map[string]any, len(clusters))
+ for _, c := range clusters {
+ per[c] = map[string]any{"n": 1}
+ }
+ return map[string]*SectionReport{"s1": {PerCluster: per}}
+}
+
+// TestScoreWithAttribution verifies score, grade, and top driver on hand-built reports.
func TestScoreWithAttribution(t *testing.T) {
t.Parallel()
tests := []struct {
@@ -17,11 +32,10 @@ func TestScoreWithAttribution(t *testing.T) {
WantGrade string
WantTopDr string
}{
- { // Test 0: Nil report scores 100 with placeholder headline.
+ { // Test 0: Nil report scores 100 ungraded with a placeholder headline.
Name: "nil report",
In: nil,
WantScore: 100,
- WantGrade: "A",
},
{ // Test 1: Empty report scores 100 with no drivers.
Name: "empty report",
@@ -33,6 +47,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "one warning",
In: &Report{
Clusters: []string{"c1"},
+ Sections: observedBy("c1"),
Findings: []Finding{{Severity: SeverityWarning}},
},
WantScore: 99,
@@ -44,6 +59,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "five criticals",
In: &Report{
Clusters: []string{"c1", "c2", "c3"},
+ Sections: observedBy("c1", "c2", "c3"),
Findings: []Finding{
{Severity: SeverityCritical},
{Severity: SeverityCritical},
@@ -60,6 +76,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "single critical cluster",
In: &Report{
Clusters: []string{"c1"},
+ Sections: observedBy("c1"),
ClusterHealths: []ClusterHealth{
{Name: "c1", Status: "critical", NodeCount: 3, HealthyNodes: 3},
},
@@ -73,6 +90,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "all caps applied",
In: &Report{
Clusters: []string{"c1", "c2"},
+ Sections: observedBy("c1", "c2"),
Findings: makeFindings(SeverityCritical, 200),
ClusterHealths: []ClusterHealth{
{Name: "c1", Status: "critical", NodeCount: 10, HealthyNodes: 0,
@@ -88,6 +106,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "critical version skew",
In: &Report{
Clusters: []string{"c1", "c2", "c3"},
+ Sections: observedBy("c1", "c2", "c3"),
ClusterHealths: []ClusterHealth{
{Name: "c1", KubernetesVersion: "v1.31.2", NodeCount: 5, HealthyNodes: 5},
{Name: "c2", KubernetesVersion: "v1.30.6", NodeCount: 5, HealthyNodes: 5},
@@ -102,6 +121,7 @@ func TestScoreWithAttribution(t *testing.T) {
Name: "worst node cluster surfaced",
In: &Report{
Clusters: []string{"a", "b"},
+ Sections: observedBy("a", "b"),
ClusterHealths: []ClusterHealth{
{Name: "a", NodeCount: 10, HealthyNodes: 10},
{Name: "b", NodeCount: 10, HealthyNodes: 5},
@@ -245,7 +265,7 @@ func TestFleetScoreProvenance(t *testing.T) {
}
opts := []cmp.Option{
cmpopts.EquateEmpty(),
- cmpopts.IgnoreFields(FleetScore{}, "Score", "Grade", "Headline", "Drivers"),
+ cmpopts.IgnoreFields(FleetScore{}, "Score", "Grade", "Headline", "Drivers", "Graded", "Coverage"),
}
if diff := cmp.Diff(want, got, opts...); diff != "" {
t.Errorf("provenance mismatch (-want +got):\n%s", diff)
@@ -382,10 +402,13 @@ func TestFleetScoreGolden(t *testing.T) { //nolint:funlen // Test function.
t.Run(fmt.Sprintf("test %d: %s", testNum, test.Name), func(t *testing.T) {
t.Parallel()
got, _ := scoreWithAttribution(test.In)
- want := FleetScore{Score: test.WantScore, Grade: test.WantGrade, Drivers: test.WantDrivers}
+ want := FleetScore{
+ Score: test.WantScore, Grade: test.WantGrade, Graded: true, Drivers: test.WantDrivers,
+ }
opts := []cmp.Option{
cmpopts.EquateEmpty(),
- cmpopts.IgnoreFields(FleetScore{}, "Headline", "SampleSize", "Dimensions", "ExcludedClusters"),
+ cmpopts.IgnoreFields(FleetScore{},
+ "Headline", "SampleSize", "Dimensions", "ExcludedClusters", "Coverage"),
}
if diff := cmp.Diff(want, got, opts...); diff != "" {
t.Errorf("score mismatch (-want +got):\n%s", diff)
@@ -415,10 +438,201 @@ func TestHeadlineThresholds(t *testing.T) {
for testNum, test := range tests {
t.Run(fmt.Sprintf("test %d", testNum), func(t *testing.T) {
t.Parallel()
- r := &Report{Clusters: make([]string, test.Clusters)}
- if diff := cmp.Diff(test.WantHeadline, headline(test.Score, r)); diff != "" {
+ fs := FleetScore{Score: test.Score, Graded: true}
+ if diff := cmp.Diff(test.WantHeadline, headline(fs, test.Clusters)); diff != "" {
t.Errorf("headline mismatch (-want +got):\n%s", diff)
}
})
}
}
+
+// coverageResults builds per-cluster results for scanners s1 to sN, all OK, then replaces the
+// runs named in override, where a missing scanner.Result removes the run.
+func coverageResults(
+ clusters []string, scanners int, override map[runKey]*scanner.Result,
+) map[string]map[string]scanner.Result {
+ out := make(map[string]map[string]scanner.Result, len(clusters))
+ for _, c := range clusters {
+ out[c] = make(map[string]scanner.Result, scanners)
+ for i := 1; i <= scanners; i++ {
+ name := fmt.Sprintf("s%d", i)
+ out[c][name] = okRun(name, map[string]any{"n": 1})
+ }
+ }
+ for k, res := range override {
+ if res == nil {
+ delete(out[k.cluster], k.scanner)
+ continue
+ }
+ out[k.cluster][k.scanner] = *res
+ }
+ return out
+}
+
+// runOf returns a pointer to res so coverage overrides read as one expression.
+func runOf(res scanner.Result) *scanner.Result {
+ return &res
+}
+
+// TestFleetCoverage verifies the coverage counts and the grading gate on built reports.
+func TestFleetCoverage(t *testing.T) { //nolint:funlen // Test function.
+ t.Parallel()
+ two := []string{"c1", "c2"}
+ five := []string{"c1", "c2", "c3", "c4", "c5"}
+ allErrored := map[runKey]*scanner.Result{}
+ for _, c := range two {
+ for _, s := range []string{"s1", "s2", "s3"} {
+ allErrored[runKey{scanner: s, cluster: c}] = runOf(erroredRun(s))
+ }
+ }
+ tests := []struct {
+ Name string
+ Clusters []string
+ Scanners int
+ Override map[runKey]*scanner.Result
+ WantCoverage FleetCoverage
+ WantGraded bool
+ WantGrade string
+ WantHeadlineHead string
+ }{{ // Test 0: Every run errored, so nothing is graded and the headline says so.
+ Name: "all errored", Clusters: two, Scanners: 3, Override: allErrored,
+ WantCoverage: FleetCoverage{ExpectedRuns: 6, BlindRuns: 6, BlindClusters: 2},
+ WantHeadlineHead: "Not enough data: 6 of 6 scanner runs did not observe the fleet",
+ }, { // Test 1: Every run OK grades normally with full coverage.
+ Name: "all ok", Clusters: two, Scanners: 2,
+ WantCoverage: FleetCoverage{ExpectedRuns: 4, ObservedRuns: 4, Fraction: 1},
+ WantGraded: true,
+ WantGrade: "A",
+ WantHeadlineHead: "2 clusters, no meaningful drift.",
+ }, { // Test 2: One errored run of ten stays above the floor and grades.
+ Name: "one errored of ten", Clusters: two, Scanners: 5,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s3", cluster: "c1"}: runOf(erroredRun("s3")),
+ },
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 10, ObservedRuns: 9, BlindRuns: 1, Fraction: 0.9,
+ },
+ WantGraded: true,
+ WantGrade: "A",
+ WantHeadlineHead: "2 clusters, nothing flagged in what was observed.",
+ }, { // Test 3: Three errored runs of ten fall under the floor.
+ Name: "three errored of ten", Clusters: two, Scanners: 5,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: runOf(erroredRun("s1")),
+ {scanner: "s2", cluster: "c2"}: runOf(erroredRun("s2")),
+ {scanner: "s3", cluster: "c1"}: runOf(erroredRun("s3")),
+ },
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 10, ObservedRuns: 7, BlindRuns: 3, Fraction: 0.7,
+ },
+ WantHeadlineHead: "Not enough data: 3 of 10 scanner runs did not observe the fleet.",
+ }, { // Test 4: A cluster no scanner observed blocks the grade even at the floor.
+ Name: "one cluster blind", Clusters: five, Scanners: 2,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c5"}: runOf(erroredRun("s1")),
+ {scanner: "s2", cluster: "c5"}: runOf(erroredRun("s2")),
+ },
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 10, ObservedRuns: 8, BlindRuns: 2, BlindClusters: 1, Fraction: 0.8,
+ },
+ WantHeadlineHead: "Not enough data: 2 of 10 scanner runs did not observe the fleet, " +
+ "and 1 of 5 clusters had no complete scanner run.",
+ }, { // Test 5: Unavailable counts as observed, degraded as neither observed nor blind.
+ Name: "unavailable and degraded", Clusters: two, Scanners: 5,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: {
+ Scanner: "s1", State: scanner.StateUnavailable, Data: map[string]any{"n": 0},
+ },
+ {scanner: "s2", cluster: "c2"}: runOf(degradedRun("s2", map[string]any{"n": 1})),
+ },
+ WantCoverage: FleetCoverage{ExpectedRuns: 10, ObservedRuns: 9, Fraction: 0.9},
+ WantGraded: true,
+ WantGrade: "A",
+ WantHeadlineHead: "2 clusters, nothing flagged in what was observed. " +
+ "1 of 10 scanner runs was partial.",
+ }, { // Test 6: A scanner that never ran on a cluster counts as a blind run.
+ Name: "absent run", Clusters: two, Scanners: 2,
+ Override: map[runKey]*scanner.Result{{scanner: "s2", cluster: "c2"}: nil},
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 4, ObservedRuns: 3, BlindRuns: 1, Fraction: 0.75,
+ },
+ WantHeadlineHead: "Not enough data: 1 of 4 scanner runs did not observe the fleet.",
+ }, { // Test 7: Exactly the floor with every cluster observed grades.
+ Name: "at the floor", Clusters: five, Scanners: 2,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: runOf(erroredRun("s1")),
+ {scanner: "s2", cluster: "c2"}: runOf(erroredRun("s2")),
+ },
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 10, ObservedRuns: 8, BlindRuns: 2, Fraction: 0.8,
+ },
+ WantGraded: true,
+ WantGrade: "A",
+ WantHeadlineHead: "5 clusters, nothing flagged in what was observed. " +
+ "2 of 10 scanner runs did not observe the fleet.",
+ }, { // Test 8: Clusters with no scanner at all are blind and ungraded.
+ Name: "no scanners", Clusters: two, Scanners: 0,
+ WantCoverage: FleetCoverage{BlindClusters: 2},
+ WantHeadlineHead: "Not enough data: No scanner ran on 2 listed clusters.",
+ }, { // Test 9: Blind and partial runs are both named.
+ Name: "blind and partial", Clusters: two, Scanners: 5,
+ Override: map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: runOf(erroredRun("s1")),
+ {scanner: "s2", cluster: "c2"}: runOf(degradedRun("s2", map[string]any{"n": 1})),
+ },
+ WantCoverage: FleetCoverage{
+ ExpectedRuns: 10, ObservedRuns: 8, BlindRuns: 1, Fraction: 0.8,
+ },
+ WantGraded: true,
+ WantGrade: "A",
+ WantHeadlineHead: "2 clusters, nothing flagged in what was observed. " +
+ "1 of 10 scanner runs did not observe the fleet and 1 was partial.",
+ }}
+ for testNum, test := range tests {
+ t.Run(fmt.Sprintf("test %d: %s", testNum, test.Name), func(t *testing.T) {
+ t.Parallel()
+ r := Build(test.Clusters, coverageResults(test.Clusters, test.Scanners, test.Override))
+ got := r.FleetScore
+ if diff := cmp.Diff(test.WantCoverage, got.Coverage); diff != "" {
+ t.Errorf("coverage mismatch (-want +got):\n%s", diff)
+ }
+ if diff := cmp.Diff(test.WantGraded, got.Graded); diff != "" {
+ t.Errorf("graded mismatch (-want +got):\n%s", diff)
+ }
+ if diff := cmp.Diff(test.WantGrade, got.Grade); diff != "" {
+ t.Errorf("grade mismatch (-want +got):\n%s", diff)
+ }
+ if !strings.HasPrefix(got.Headline, test.WantHeadlineHead) {
+ t.Errorf("headline %q, want prefix %q", got.Headline, test.WantHeadlineHead)
+ }
+ label := fmt.Sprintf(" Observed-only score %d.", got.Score)
+ if !got.Graded && !strings.HasSuffix(got.Headline, label) {
+ t.Errorf("ungraded headline %q does not label the observed-only score", got.Headline)
+ }
+ if got.Coverage.BlindRuns > 0 && strings.Contains(got.Headline, "no meaningful drift") {
+ t.Errorf("headline %q claims no drift with blind runs", got.Headline)
+ }
+ })
+ }
+}
+
+// TestFleetCoverageDecoded verifies a report decoded from JSON yields the coverage Build
+// computed, so a stored report rescored after a load grades the same way.
+func TestFleetCoverageDecoded(t *testing.T) {
+ t.Parallel()
+ clusters := []string{"c1", "c2"}
+ built := Build(clusters, coverageResults(clusters, 3, map[runKey]*scanner.Result{
+ {scanner: "s1", cluster: "c1"}: runOf(erroredRun("s1")),
+ }))
+ blob, err := json.Marshal(built)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var decoded Report
+ if err := json.Unmarshal(blob, &decoded); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if diff := cmp.Diff(built.FleetScore.Coverage, fleetCoverage(&decoded)); diff != "" {
+ t.Errorf("decoded coverage mismatch (-want +got):\n%s", diff)
+ }
+}
From 7bc9cd4aebc5fb65a96184fc7f7d040dedd49d1b Mon Sep 17 00:00:00 2001
From: Douglas Adolph <116844282+dcadolph@users.noreply.github.com>
Date: Sat, 31 Oct 2026 07:05:03 -0500
Subject: [PATCH 06/13] Mark clusters unknown when a scanner run did not
observe them
---
cmd/cmd_top.go | 4 +-
cmd/cmd_top_test.go | 12 ++--
docs/integrations/prometheus.md | 2 +-
internal/compare/compare.go | 4 +-
internal/compare/compare_test.go | 29 ++++++++++
internal/report/cluster_score.go | 13 ++++-
internal/report/cluster_score_test.go | 31 ++++++++++
internal/report/findings.go | 15 ++++-
internal/report/findings_test.go | 81 +++++++++++++++++++++++++++
internal/server/geo_handlers.go | 2 +-
internal/server/metrics.go | 9 ++-
internal/server/metrics_otel.go | 3 +-
internal/server/metrics_test.go | 3 +
internal/server/openapi.yaml | 2 +-
14 files changed, 191 insertions(+), 19 deletions(-)
diff --git a/cmd/cmd_top.go b/cmd/cmd_top.go
index 5682a35..e8cdf8c 100644
--- a/cmd/cmd_top.go
+++ b/cmd/cmd_top.go
@@ -270,7 +270,7 @@ func (s *topState) lessFn(rows []topRow) func(i, j int) bool {
case sortByName:
return func(i, j int) bool { return rows[i].Cluster < rows[j].Cluster }
case sortByStatus:
- order := map[string]int{"critical": 0, "degraded": 1, "busy": 2, "healthy": 3}
+ order := map[string]int{"critical": 0, "degraded": 1, "busy": 2, "unknown": 3, "healthy": 4}
return func(i, j int) bool {
if order[rows[i].Status] != order[rows[j].Status] {
return order[rows[i].Status] < order[rows[j].Status]
@@ -507,6 +507,8 @@ func statusColor(status string) string {
return "33"
case "busy":
return "34"
+ case "unknown":
+ return "90"
default:
return "32"
}
diff --git a/cmd/cmd_top_test.go b/cmd/cmd_top_test.go
index 5d74514..5354da2 100644
--- a/cmd/cmd_top_test.go
+++ b/cmd/cmd_top_test.go
@@ -70,7 +70,7 @@ func TestColorCodeHelpers(t *testing.T) {
// Test 0: statusColor mapping.
statusCases := map[string]string{
"critical": "31", "degraded": "33", "strained": "33",
- "busy": "34", "healthy": "32", "unknown": "32",
+ "busy": "34", "healthy": "32", "unknown": "90",
}
for status, want := range statusCases {
if got := statusColor(status); got != want {
@@ -214,15 +214,19 @@ func TestLessFn(t *testing.T) {
{Cluster: "beta", Status: "healthy", Score: 90},
{Cluster: "alpha", Status: "critical", Score: 40},
{Cluster: "gamma", Status: "busy", Score: 70},
+ {Cluster: "delta", Status: "unknown", Score: 95},
}
tests := []struct {
WantOrder []string
Mode topSortMode
}{
- {WantOrder: []string{"alpha", "gamma", "beta"}, Mode: sortByScore}, // Test 0: Worst score first.
- {WantOrder: []string{"alpha", "beta", "gamma"}, Mode: sortByName}, // Test 1: Alphabetical.
- {WantOrder: []string{"alpha", "gamma", "beta"}, Mode: sortByStatus}, // Test 2: critical 0 {
+ h.Status = "unknown"
+ }
healths = append(healths, h)
}
diff --git a/internal/report/findings_test.go b/internal/report/findings_test.go
index decfda4..07d99d3 100644
--- a/internal/report/findings_test.go
+++ b/internal/report/findings_test.go
@@ -1509,6 +1509,87 @@ func TestClusterHealthOwnFindings(t *testing.T) {
}
}
+// TestClusterHealthUnknown verifies a cluster with a blind scanner run and nothing charging it
+// reads unknown, not healthy, and that findings still outrank the unknown. Other replaces the
+// second cluster's runs when set.
+func TestClusterHealthUnknown(t *testing.T) { //nolint:funlen // Test function.
+ t.Parallel()
+ ns := okRun("namespaces", map[string]any{"count": 3})
+ quotas := func(n int) scanner.Result {
+ return okRun("resource-quotas", map[string]any{"namespaces_with_quotas": n})
+ }
+ tests := []struct {
+ Name string
+ Runs map[string]scanner.Result
+ Other map[string]scanner.Result
+ WantStatus string
+ WantBlind int
+ }{{ // Test 0: Every run errored and no finding charges the cluster.
+ Name: "all errored",
+ Runs: map[string]scanner.Result{
+ "namespaces": erroredRun("namespaces"),
+ "resource-quotas": erroredRun("resource-quotas"),
+ },
+ WantStatus: "unknown", WantBlind: 2,
+ }, { // Test 1: One errored run is enough when nothing else charges the cluster.
+ Name: "one errored",
+ Runs: map[string]scanner.Result{
+ "namespaces": ns, "resource-quotas": erroredRun("resource-quotas"),
+ },
+ WantStatus: "unknown", WantBlind: 1,
+ }, { // Test 2: A warning finding outranks the errored run.
+ Name: "errored with a warning",
+ Runs: map[string]scanner.Result{
+ "namespaces": ns, "resource-quotas": quotas(0), "certs": erroredRun("certs"),
+ },
+ Other: map[string]scanner.Result{
+ "namespaces": ns, "resource-quotas": quotas(3),
+ "certs": okRun("certs", map[string]any{}),
+ },
+ WantStatus: "degraded", WantBlind: 1,
+ }, { // Test 3: A degraded run is partial, not blind, so the cluster stays healthy.
+ Name: "degraded only",
+ Runs: map[string]scanner.Result{
+ "namespaces": ns,
+ "resource-quotas": degradedRun("resource-quotas",
+ map[string]any{"namespaces_with_quotas": 3}),
+ },
+ WantStatus: "healthy",
+ }, { // Test 4: Every run OK and nothing charges the cluster.
+ Name: "all ok",
+ Runs: map[string]scanner.Result{"namespaces": ns, "resource-quotas": quotas(3)},
+ WantStatus: "healthy",
+ }, { // Test 5: A scanner that ran on another cluster but never on this one is blind here.
+ Name: "absent run",
+ Runs: map[string]scanner.Result{"resource-quotas": quotas(3)},
+ WantStatus: "unknown", WantBlind: 1,
+ }}
+ for testNum, test := range tests {
+ t.Run(fmt.Sprintf("test %d: %s", testNum, test.Name), func(t *testing.T) {
+ t.Parallel()
+ other := test.Other
+ if other == nil {
+ other = map[string]scanner.Result{"namespaces": ns, "resource-quotas": quotas(3)}
+ }
+ r := Build([]string{"c1", "c2"},
+ map[string]map[string]scanner.Result{"c1": test.Runs, "c2": other})
+ got := map[string]ClusterHealth{}
+ for _, h := range r.ClusterHealths {
+ got[h.Name] = h
+ }
+ if diff := cmp.Diff(test.WantStatus, got["c1"].Status); diff != "" {
+ t.Errorf("c1 status mismatch (-want +got):\n%s", diff)
+ }
+ if diff := cmp.Diff(test.WantBlind, got["c1"].BlindScanners); diff != "" {
+ t.Errorf("c1 blind scanners mismatch (-want +got):\n%s", diff)
+ }
+ if diff := cmp.Diff("healthy", got["c2"].Status); diff != "" {
+ t.Errorf("c2 status mismatch (-want +got):\n%s", diff)
+ }
+ })
+ }
+}
+
// TestNodeHealthFindings verifies pressure findings name the affected nodes.
func TestNodeHealthFindings(t *testing.T) {
t.Parallel()
diff --git a/internal/server/geo_handlers.go b/internal/server/geo_handlers.go
index 77bde17..9e37dc5 100644
--- a/internal/server/geo_handlers.go
+++ b/internal/server/geo_handlers.go
@@ -19,7 +19,7 @@ import (
type geoPoint struct {
// Cluster is the kubeconfig context name.
Cluster string `json:"cluster"`
- // Status is healthy, busy, degraded, or critical (drives globe color).
+ // Status is healthy, busy, unknown, degraded, or critical (drives globe color).
Status string `json:"status"`
// Provider is the cloud provider for auto-detected entries.
Provider string `json:"provider,omitempty"`
diff --git a/internal/server/metrics.go b/internal/server/metrics.go
index 2c2f31f..a1c09e9 100644
--- a/internal/server/metrics.go
+++ b/internal/server/metrics.go
@@ -15,6 +15,12 @@ import (
"github.com/dcadolph/fleetsweeper/internal/scanner/policyreportingest"
)
+// clusterStatuses lists every cluster health status the metrics export one series for, so a
+// cluster in any status has exactly one series at 1.
+func clusterStatuses() []string {
+ return []string{"healthy", "busy", "unknown", "degraded", "critical"}
+}
+
// writeMetrics emits the Prometheus exposition for the server's current state
// to w. The function is structured top-down: counters that always exist first,
// then per-scan gauges, then per-cluster and per-finding labels. When no scan
@@ -102,9 +108,8 @@ func (s *Server) writeMetrics(ctx context.Context, w io.Writer) {
emit(w, "# HELP fleetsweeper_cluster_health Cluster status indicator (1 = cluster is in that status, 0 = not).")
emit(w, "# TYPE fleetsweeper_cluster_health gauge")
- statuses := []string{"healthy", "busy", "degraded", "critical"}
for _, ch := range r.ClusterHealths {
- for _, st := range statuses {
+ for _, st := range clusterStatuses() {
v := 0
if ch.Status == st {
v = 1
diff --git a/internal/server/metrics_otel.go b/internal/server/metrics_otel.go
index 996b16e..e11bea2 100644
--- a/internal/server/metrics_otel.go
+++ b/internal/server/metrics_otel.go
@@ -113,9 +113,8 @@ func (s *Server) initOTelMetrics() error {
metric.WithAttributes(attribute.String("severity", sev)))
}
- statuses := []string{"healthy", "busy", "degraded", "critical"}
for _, ch := range r.ClusterHealths {
- for _, st := range statuses {
+ for _, st := range clusterStatuses() {
v := int64(0)
if ch.Status == st {
v = 1
diff --git a/internal/server/metrics_test.go b/internal/server/metrics_test.go
index e092cb4..93380de 100644
--- a/internal/server/metrics_test.go
+++ b/internal/server/metrics_test.go
@@ -73,6 +73,9 @@ func TestWriteMetrics_DemoMode(t *testing.T) {
mustContain(t, out, "fleetsweeper_fleet_score ")
mustContain(t, out, "fleetsweeper_findings_total{severity=\"critical\"}")
mustContain(t, out, "fleetsweeper_cluster_health{cluster=")
+ // The demo's edge cluster has a forbidden metrics read and no finding, so it reads unknown.
+ mustContain(t, out, `fleetsweeper_cluster_health{cluster="edge-lagos",status="unknown"} 1`)
+ mustContain(t, out, `fleetsweeper_cluster_health{cluster="edge-lagos",status="healthy"} 0`)
mustContain(t, out, "fleetsweeper_finding_count{severity=")
if !strings.HasSuffix(out, "\n") {
t.Errorf("metrics output does not end with newline")
diff --git a/internal/server/openapi.yaml b/internal/server/openapi.yaml
index 3bbea38..083c9ed 100644
--- a/internal/server/openapi.yaml
+++ b/internal/server/openapi.yaml
@@ -176,7 +176,7 @@ components:
required: [name, status]
properties:
name: {type: string}
- status: {type: string, enum: [healthy, busy, degraded, critical]}
+ status: {type: string, enum: [healthy, busy, unknown, degraded, critical]}
kubernetes_version: {type: string}
node_count: {type: integer}
healthy_nodes: {type: integer}
From f4cdd786dbad8787be3405920328142e3be08f69 Mon Sep 17 00:00:00 2001
From: Douglas Adolph <116844282+dcadolph@users.noreply.github.com>
Date: Sat, 31 Oct 2026 07:08:09 -0500
Subject: [PATCH 07/13] Show coverage and unknown status on the dashboard
---
internal/browser/browser_test.go | 66 +++++++++++++++++++
internal/report/templates/report.html | 11 ++--
internal/server/static/css/app.css | 2 +
.../static/js/components/cluster-table.js | 6 +-
.../server/static/js/components/score-card.js | 19 +++++-
internal/server/static/js/live.js | 2 +-
internal/server/static/js/views/dash.js | 6 +-
internal/server/static/js/views/globe.js | 6 +-
8 files changed, 100 insertions(+), 18 deletions(-)
diff --git a/internal/browser/browser_test.go b/internal/browser/browser_test.go
index 3075d1d..d1de0cd 100644
--- a/internal/browser/browser_test.go
+++ b/internal/browser/browser_test.go
@@ -23,6 +23,7 @@ import (
"go.uber.org/zap"
"github.com/dcadolph/fleetsweeper/internal/scanner"
+ "github.com/dcadolph/fleetsweeper/internal/scanner/metrics"
"github.com/dcadolph/fleetsweeper/internal/server"
"github.com/dcadolph/fleetsweeper/internal/store"
)
@@ -685,3 +686,68 @@ func TestDashboardEmpty(t *testing.T) {
}
}
}
+
+// TestDashboardUngraded saves a scan in which every scanner run errored and checks the score
+// card says "Not graded" with its coverage line, shows no letter grade, and the page logs no
+// console errors.
+func TestDashboardUngraded(t *testing.T) {
+ st, err := store.NewSQLite(filepath.Join(t.TempDir(), "ungraded.db"))
+ if err != nil {
+ t.Fatalf("open store: %v", err)
+ }
+ clusters := []string{"blind-a", "blind-b", "blind-c"}
+ results := map[string]map[string]scanner.Result{}
+ for _, c := range clusters {
+ results[c] = map[string]scanner.Result{metrics.Name: {
+ Scanner: metrics.Name, State: scanner.StateErrored, Reason: "forbidden", Data: metrics.Data{},
+ }}
+ }
+ rec := store.ScanRecord{ID: "ungraded-01", Timestamp: time.Now().UTC().Truncate(time.Minute), Clusters: clusters}
+ if _, err := st.SaveScanRecord(t.Context(), rec, results); err != nil {
+ t.Fatalf("save scan: %v", err)
+ }
+ srv := server.New(server.Config{
+ Store: st, Registry: scanner.NewRegistry(), Log: zap.NewNop(), Workers: 2, Demo: true,
+ })
+ ts := httptest.NewServer(srv.Handler())
+ t.Cleanup(func() {
+ ts.Close()
+ srv.Close()
+ st.Close()
+ })
+
+ ctx := newBrowser(t)
+ log := &consoleLog{route: "boot"}
+ log.listen(ctx)
+ boot(t, ctx, ts)
+ hash, err := visit(ctx, "dash", clusters[0], rec.ID, chromedp.ActionFunc(func(context.Context) error { return nil }))
+ if err != nil {
+ t.Fatalf("dash (%s): view never settled: %v", hash, err)
+ }
+ var card, grade, table string
+ if err := run(ctx, 10*time.Second,
+ chromedp.Poll(`!!document.querySelector('.score-card')`, nil, chromedp.WithPollingTimeout(settleTimeout)),
+ chromedp.Evaluate(`document.querySelector('.score-card').innerText`, &card),
+ chromedp.Evaluate(`document.querySelectorAll('.sc-grade:not(.sc-grade-none)').length + ''`, &grade),
+ chromedp.Evaluate(`document.querySelector('#ct').innerText`, &table),
+ ); err != nil {
+ t.Fatalf("read score card: %v", err)
+ }
+ for _, want := range []string{"Not graded", "Not enough data"} {
+ if !strings.Contains(card, want) {
+ t.Errorf("score card lacks %q:\n%s", want, card)
+ }
+ }
+ if !regexp.MustCompile(`\d+ of \d+ scanner runs observed \(3 clusters blind\)\.`).MatchString(card) {
+ t.Errorf("score card lacks the coverage line:\n%s", card)
+ }
+ if grade != "0" {
+ t.Errorf("score card renders %s letter grades, want 0", grade)
+ }
+ if !strings.Contains(table, "unknown") {
+ t.Errorf("cluster table shows no unknown status:\n%s", table)
+ }
+ if errs := log.take(); len(errs) > 0 {
+ t.Errorf("console errors:\n%s", strings.Join(errs, "\n"))
+ }
+}
diff --git a/internal/report/templates/report.html b/internal/report/templates/report.html
index 679a5b5..024c3ca 100644
--- a/internal/report/templates/report.html
+++ b/internal/report/templates/report.html
@@ -242,8 +242,8 @@
h+='
';
(R.cluster_healths||[]).forEach(function(ch){
if(hiddenClusters[ch.name])return;
- var sc=ch.status==='critical'?'var(--cr)':ch.status==='degraded'?'var(--wn)':'var(--ok)';
- var sb=ch.status==='critical'?'var(--crb)':ch.status==='degraded'?'var(--wnb)':'var(--okb)';
+ var sc=ch.status==='critical'?'var(--cr)':ch.status==='degraded'?'var(--wn)':ch.status==='unknown'?'var(--t3)':'var(--ok)';
+ var sb=ch.status==='critical'?'var(--crb)':ch.status==='degraded'?'var(--wnb)':ch.status==='unknown'?'rgba(139,148,158,.12)':'var(--okb)';
h+='
';
h+='
'+esc(ch.name)+'
';
h+=''+ch.status+'';
@@ -293,8 +293,8 @@
var h='
';
(R.cluster_healths||[]).forEach(function(ch){
if(hiddenClusters[ch.name])return;
- var sc=ch.status==='critical'?'var(--cr)':ch.status==='degraded'?'var(--wn)':'var(--ok)';
- var sb=ch.status==='critical'?'var(--crb)':ch.status==='degraded'?'var(--wnb)':'var(--okb)';
+ var sc=ch.status==='critical'?'var(--cr)':ch.status==='degraded'?'var(--wn)':ch.status==='unknown'?'var(--t3)':'var(--ok)';
+ var sb=ch.status==='critical'?'var(--crb)':ch.status==='degraded'?'var(--wnb)':ch.status==='unknown'?'rgba(139,148,158,.12)':'var(--okb)';
h+='
';
h+='
'+esc(ch.name)+'
';
h+=''+ch.status+'';
@@ -383,7 +383,7 @@
var vis=R.clusters.filter(function(c){return !hiddenClusters[c]});
var colors=vis.map(function(c){return CC[c]});
var bgColors=vis.map(function(c){return CC[c]+'40'});
- function getData(scanner,field){var sec=R.sections[scanner];return vis.map(function(c){if(!sec||!sec.per_cluster[c])return 0;var d=JSON.parse(JSON.stringify(sec.per_cluster[c]));return d[field]||0})}
+ function getData(scanner,field){var sec=R.sections[scanner];return vis.map(function(c){if(!sec||!sec.per_cluster[c])return null;var v=sec.per_cluster[c][field];return typeof v==='number'?v:null})}
// CPU
var el=document.getElementById('cpuC');
@@ -423,6 +423,7 @@
function drawGauge(id,value,color){
var el=document.getElementById(id);if(!el)return;
+ if(typeof value!=='number'){el.style.display='none';var na=document.createElement('div');na.textContent='N/A';na.style.cssText='color:var(--t3);font-size:14px;text-align:center';el.parentNode.insertBefore(na,el.nextSibling);return}
new Chart(el,{type:'doughnut',data:{datasets:[{data:[value,100-value],backgroundColor:[color,'#21262d'],borderWidth:0}]},options:{responsive:false,cutout:'75%',rotation:-90,circumference:180,plugins:{legend:{display:false},tooltip:{enabled:false}},animation:{animateRotate:true}},plugins:[{id:'gaugeText',afterDraw:function(chart){var ctx=chart.ctx;var w=chart.width/2;var h=chart.height-20;ctx.save();ctx.textAlign='center';ctx.fillStyle=value>85?'#f85149':value>70?'#d29922':'#e6edf3';ctx.font='bold 20px -apple-system,sans-serif';ctx.fillText(Math.round(value)+'%',w,h);ctx.restore()}}]});
}
diff --git a/internal/server/static/css/app.css b/internal/server/static/css/app.css
index d15d0e7..6f291ca 100644
--- a/internal/server/static/css/app.css
+++ b/internal/server/static/css/app.css
@@ -306,6 +306,7 @@ a.cc:hover { text-decoration: none; }
.sc-main { display: grid; grid-template-columns: auto auto; align-items: baseline; column-gap: 10px; }
.sc-num { font-size: var(--fs-display); font-weight: 700; line-height: 1; font-variant-numeric: tabular-nums; }
.sc-grade { font-size: var(--fs-28); font-weight: 700; }
+.sc-grade-none { font-size: var(--fs-14); font-weight: 600; }
.sc-main .eyebrow { grid-column: 1 / -1; margin-top: 6px; }
.sc-side { flex: 1 1 260px; min-width: 0; }
.sc-move { font-size: var(--fs-14); margin-bottom: 4px; }
@@ -776,3 +777,4 @@ kbd {
.meter-value { font-size: var(--fs-28); font-weight: 700; font-variant-numeric: tabular-nums; }
.meter-bar { width: 100%; height: 6px; margin-top: 6px; }
.whatif-score { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-bottom: 8px; }
+.c-muted { color: var(--text-3); }
diff --git a/internal/server/static/js/components/cluster-table.js b/internal/server/static/js/components/cluster-table.js
index ba47676..2f03223 100644
--- a/internal/server/static/js/components/cluster-table.js
+++ b/internal/server/static/js/components/cluster-table.js
@@ -11,13 +11,13 @@ import { on } from '../actions.js';
const SHOWN = 10;
// STATUS_RANK orders statuses worst first.
-const STATUS_RANK = { critical: 0, degraded: 1, busy: 2, healthy: 3 };
+const STATUS_RANK = { critical: 0, degraded: 1, busy: 2, unknown: 3, healthy: 4 };
// COLUMNS lists the sortable columns: key, header, tooltip, whether larger
// sorts first, and the numeric value of a row.
const COLUMNS = [
{ key: 'cluster', label: 'Cluster', value: (r) => r.cluster },
- { key: 'status', label: 'Status', tip: 'Correlated status from findings and utilization.', value: (r) => STATUS_RANK[r.status] ?? 4 },
+ { key: 'status', label: 'Status', tip: 'Correlated status from findings and utilization.', value: (r) => STATUS_RANK[r.status] ?? 5 },
{ key: 'cost', label: 'Score cost', tip: 'Fleet score points this cluster costs.', desc: true, value: (r) => r.cost },
{ key: 'mass', label: 'Deviation', tip: 'Deviation mass: the sum of capped |z| over every field, how far the cluster sits from the norm.', desc: true, value: (r) => r.mass },
{ key: 'critical', label: 'Critical', desc: true, value: (r) => r.critical },
@@ -31,7 +31,7 @@ const state = { rows: [], sort: null, all: false };
// defaultOrder sorts worst first: status, then score cost, then deviation.
function defaultOrder(a, b) {
- return ((STATUS_RANK[a.status] ?? 4) - (STATUS_RANK[b.status] ?? 4)) || (b.cost - a.cost) || (b.mass - a.mass) || a.cluster.localeCompare(b.cluster);
+ return ((STATUS_RANK[a.status] ?? 5) - (STATUS_RANK[b.status] ?? 5)) || (b.cost - a.cost) || (b.mass - a.mass) || a.cluster.localeCompare(b.cluster);
}
// sortedRows returns the rows in the current order.
diff --git a/internal/server/static/js/components/score-card.js b/internal/server/static/js/components/score-card.js
index f087226..82071f3 100644
--- a/internal/server/static/js/components/score-card.js
+++ b/internal/server/static/js/components/score-card.js
@@ -31,6 +31,14 @@ export function topTerms(attribution, n) {
return ((attribution && attribution.terms) || []).filter((t) => t.cost > 0).slice().sort((a, b) => b.cost - a.cost).slice(0, n);
}
+// coverageLine returns the scanner coverage sentence for a score's coverage,
+// or an empty string when the report carries none.
+export function coverageLine(cov) {
+ if (!cov || !(cov.expected_runs > 0)) return '';
+ const blind = cov.blind_clusters || 0;
+ return `${cov.observed_runs} of ${cov.expected_runs} scanner runs observed (${blind} cluster${blind === 1 ? '' : 's'} blind).`;
+}
+
// moveLine returns the line for the score's move since the previous scan and
// the projection for the next one, or an empty string when neither is known.
export function moveLine(score, prev, forecast) {
@@ -56,8 +64,9 @@ export function moveLine(score, prev, forecast) {
// action, tip} for the scan's counts.
export function renderScoreCard(fs, attribution, prev, forecast, facts) {
if (!fs || typeof fs.score !== 'number') return '';
- const tone = scoreTone(fs.score);
- const gradeTone = GRADE_TONES[fs.grade] || 't2';
+ const graded = fs.graded !== false && !!fs.grade;
+ const tone = graded ? scoreTone(fs.score) : 't2';
+ const gradeTone = graded ? GRADE_TONES[fs.grade] || 't2' : 't2';
let prov = '';
if (fs.sample_size > 0) {
prov = `Scored from ${fs.sample_size} cluster${fs.sample_size === 1 ? '' : 's'} across ${fs.dimensions || 0} dimension${fs.dimensions === 1 ? '' : 's'}.`;
@@ -65,6 +74,8 @@ export function renderScoreCard(fs, attribution, prev, forecast, facts) {
} else {
prov = fs.headline || 'No clusters scored yet.';
}
+ if (!graded && fs.headline && fs.sample_size > 0) prov = fs.headline + ' ' + prov;
+ const cov = coverageLine(fs.coverage);
const chips = topTerms(attribution, 3).map((t) =>
``).join('');
@@ -77,9 +88,11 @@ export function renderScoreCard(fs, attribution, prev, forecast, facts) {
}).join('');
return `` +
`