From 07aab77fb8f506bcfc011ddf950bb10e7f714741 Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 23 Jul 2026 15:08:41 -0500 Subject: [PATCH] dashboard: label progress as current page --- deploy/grafana/stream.json | 10 +++++----- docs/grafana-dashboard.md | 17 +++++++++-------- tests/test_dashboard_contract.py | 4 ++-- tools/adapt_dashboard.py | 12 ++++++------ tools/check_dashboard.py | 2 +- 5 files changed, 23 insertions(+), 22 deletions(-) diff --git a/deploy/grafana/stream.json b/deploy/grafana/stream.json index 3658b6b..45e76cd 100644 --- a/deploy/grafana/stream.json +++ b/deploy/grafana/stream.json @@ -42,7 +42,7 @@ } ] }, - "description": "Stream operational dashboard adapted from the checksum-pinned Jetstream V2 dashboard. Protocol and lifecycle rows are unchanged; the runtime row uses Stream process metrics, and final Stream-only rows expose live full-network progress and scheduler health.", + "description": "Stream operational dashboard adapted from the checksum-pinned Jetstream V2 dashboard. Protocol and lifecycle rows are unchanged; the runtime row uses Stream process metrics, and final Stream-only rows expose current-page backfill work and scheduler health.", "editable": true, "fiscalYearStartMonth": 0, "graphTooltip": 1, @@ -7214,7 +7214,7 @@ { "id": 80, "type": "row", - "title": "Stream experiment progress", + "title": "Backfill work in progress", "collapsed": false, "gridPos": { "h": 1, @@ -7223,13 +7223,13 @@ "y": 170 }, "panels": [], - "description": "A live, honest view of the current whole-network bootstrap frontier." + "description": "The final network denominator is unknown until listRepos discovery finishes." }, { "id": 81, "type": "bargauge", - "title": "Full-network backfill", - "description": "Processed repositories move continuously; durably committed repositories advance after each page checkpoint. Both use repositories discovered so far as their denominator, which expands during listRepos traversal.", + "title": "Current discovery page", + "description": "Processed repositories move continuously; durably committed repositories advance after the page checkpoint. This is progress through the current listRepos page, not a percentage of the full network.", "datasource": { "type": "prometheus", "uid": "${datasource}" diff --git a/docs/grafana-dashboard.md b/docs/grafana-dashboard.md index 66eb34e..7138a90 100644 --- a/docs/grafana-dashboard.md +++ b/docs/grafana-dashboard.md @@ -11,18 +11,19 @@ The exact reviewed bytes are vendored at `deploy/grafana/jetstream-upstream.json`; deployment does not depend on the network or a moving branch. Stream provisions `deploy/grafana/stream.json` (SHA-256 -`74567e45fd1035e9b3e474f025d56329af970b944f177aa57360bf878999dae4`). It is +`7f73d578d941584e70f6f90745a9417596e973538cdb4c80e0473cead92e7f66`). It is deterministically generated by `tools/adapt_dashboard.py` from the pinned source. The generator refuses a changed source checksum, and the tests prove every upstream non-runtime panel remains structurally identical. Stream adds two explicit final rows. The first pairs a continuously moving processed-repo -bar with upstream's durable page-commit ratio, while stating that their -discovered-repository denominator expands during `listRepos` traversal. The -second covers the scheduler, which has no upstream Go equivalent: ticket -boundaries, exact unsettled stage gaps, current fatal state, and first-failure -counters partitioned by scheduler/emit/repair/cursor stage. These producers are -active during historical bootstrap as well as steady state; the dashboard -never infers scheduler health from archive throughput. +bar with upstream's durable page-commit ratio and labels both as progress +through the current `listRepos` page. It does not present that page ratio as +whole-network completion: the final network denominator is unknown until +discovery finishes. The second covers the scheduler, which has no upstream Go +equivalent: ticket boundaries, exact unsettled stage gaps, current fatal state, +and first-failure counters partitioned by scheduler/emit/repair/cursor stage. +These producers are active during historical bootstrap as well as steady +state; the dashboard never infers scheduler health from archive throughput. `just dashboard-test` verifies both checksums, regeneration, and the contract parser. `just dashboard-contract ` extracts every diff --git a/tests/test_dashboard_contract.py b/tests/test_dashboard_contract.py index f8d75bb..b947c6b 100644 --- a/tests/test_dashboard_contract.py +++ b/tests/test_dashboard_contract.py @@ -66,8 +66,8 @@ class DashboardContractTest(unittest.TestCase): progress = stream_panels[81] self.assertEqual("bargauge", progress["type"]) - self.assertEqual("Full-network backfill", progress["title"]) - self.assertIn("denominator", progress["description"]) + self.assertEqual("Current discovery page", progress["title"]) + self.assertIn("not a percentage of the full network", progress["description"]) self.assertEqual( upstream_panels[23]["targets"][0]["expr"], progress["targets"][1]["expr"], diff --git a/tools/adapt_dashboard.py b/tools/adapt_dashboard.py index 2b38723..ad15ba0 100644 --- a/tools/adapt_dashboard.py +++ b/tools/adapt_dashboard.py @@ -41,11 +41,11 @@ def progress_panel(template: dict) -> dict: panel.update( id=81, type="bargauge", - title="Full-network backfill", + title="Current discovery page", description=( "Processed repositories move continuously; durably committed repositories advance " - "after each page checkpoint. Both use repositories discovered so far as their " - "denominator, which expands during listRepos traversal." + "after the page checkpoint. This is progress through the current listRepos page, " + "not a percentage of the full network." ), gridPos={"h": 4, "w": 24, "x": 0, "y": 171}, ) @@ -160,8 +160,8 @@ def adapt(raw: bytes) -> bytes: progress_row = copy.deepcopy(panels[75]) progress_row.update( id=80, - title="Stream experiment progress", - description="A live, honest view of the current whole-network bootstrap frontier.", + title="Backfill work in progress", + description="The final network denominator is unknown until listRepos discovery finishes.", gridPos={"h": 1, "w": 24, "x": 0, "y": 170}, ) progress = progress_panel(panels[23]) @@ -247,7 +247,7 @@ def adapt(raw: bytes) -> bytes: dashboard["description"] = ( "Stream operational dashboard adapted from the checksum-pinned Jetstream V2 dashboard. " "Protocol and lifecycle rows are unchanged; the runtime row uses Stream process metrics, " - "and final Stream-only rows expose live full-network progress and scheduler health." + "and final Stream-only rows expose current-page backfill work and scheduler health." ) return (json.dumps(dashboard, indent=2, ensure_ascii=False) + "\n").encode() diff --git a/tools/check_dashboard.py b/tools/check_dashboard.py index 0d9f8c5..9107f65 100755 --- a/tools/check_dashboard.py +++ b/tools/check_dashboard.py @@ -17,7 +17,7 @@ UPSTREAM_DASHBOARD = ROOT / "deploy/grafana/jetstream-upstream.json" DEFAULT_DASHBOARD = ROOT / "deploy/grafana/stream.json" EXPECTED_SHA256 = { UPSTREAM_DASHBOARD.resolve(): "ef6033c182d8c3f9d88af7d91e61126724efbe72e6b940984c9de12e9530cd91", - DEFAULT_DASHBOARD.resolve(): "74567e45fd1035e9b3e474f025d56329af970b944f177aa57360bf878999dae4", + DEFAULT_DASHBOARD.resolve(): "7f73d578d941584e70f6f90745a9417596e973538cdb4c80e0473cead92e7f66", } METRIC_RE = re.compile(r"\b(?:jetstream|go|process|stream)_[a-zA-Z_:][a-zA-Z0-9_:]*") TYPE_RE = re.compile(r"^# TYPE ([a-zA-Z_:][a-zA-Z0-9_:]*) (\w+)$") -- 2.54.0