metric: replace 10 duplicated bucket literals with leanSpec-named constants (#303)#304
Open
mananuf wants to merge 1 commit into
Open
metric: replace 10 duplicated bucket literals with leanSpec-named constants (#303)#304mananuf wants to merge 1 commit into
mananuf wants to merge 1 commit into
Conversation
…stants (#303) Ten of gean's histograms in node/metrics.go used inline []float64 literals whose values already matched one of the four named bucket constants leanSpec defines in subspecs/metrics/registry.py:36-45. The literals were copy-pasted across the file — same bucket boundaries duplicated 2-6 times per shape. Add 4 package-private vars (forkChoiceBlockBuckets, attestationValidationBuckets, stateTransitionBuckets, reorgDepthBuckets) at the top of the Histograms block, with a cross-reference comment to the spec line numbers. Replace the 10 matching Buckets: lines with references to the named vars. Zero behavior change: each replaced literal had the same values as the named constant it now points to. Verified by reading the spec file side-by-side and by go test ./node/... passing. Spec-compliance: addresses the standing⚠️ flag from /spec-compliant devnet3 head ("Histogram bucket boundaries should be cross-checked vs spec constants"). Bucket boundaries used in gean are now traceable to a spec constant via grep. 11 histograms remain hand-rolled — mostly non-time metrics (byte sizes, payload counts, coverage ratios) where the spec's four time-bucket constants don't semantically apply. Left as-is. Closes #303.
This was referenced May 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ten of gean's 21 histograms in `node/metrics.go` had inline `[]float64` bucket literals whose values already matched one of the four named bucket constants leanSpec defines in `subspecs/metrics/registry.py:36-45`. Same bucket boundaries copy-pasted 2-6 times per latency shape. Replaces them with 4 named package-private vars that mirror the spec.
Closes #303.
What changed
Single file, `node/metrics.go`: +25 / -15.
Added (4 vars at top of histograms block)
```go
// Bucket sets mirror leanSpec's named constants in
// lean_spec/subspecs/metrics/registry.py:36-45. Defined here once so the
// histograms that share these shapes don't each carry a duplicated literal
// that can drift out of spec alignment silently. Histograms whose latency
// shape doesn't fit any of the four spec constants use their own hand-rolled
// bucket array inline and note that fact in a comment.
var (
forkChoiceBlockBuckets = []float64{0.005, 0.01, 0.025, 0.05, 0.1, 1, 1.25, 1.5, 2, 4}
attestationValidationBuckets = []float64{0.005, 0.01, 0.025, 0.05, 0.1, 1}
stateTransitionBuckets = []float64{0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 2.5, 3, 4}
reorgDepthBuckets = []float64{1, 2, 3, 5, 7, 10, 20, 30, 50, 100}
)
```
Replaced (10 histograms)
Out of scope (11 histograms left hand-rolled)
These either don't measure time at all (byte sizes, payload counts, coverage ratios) or measure a time shape no spec bucket constant covers (`block_building`, `attestations_production`, aggregated-sig building/verification, full-block sig verification). Left alone.
Zero behavior change
Each replaced literal had the same values byte-for-byte as the named constant it now points to. Verified by reading the leanSpec file side-by-side and by:
A `/metrics` scrape post-merge will produce byte-identical bucket boundaries for the 10 affected histograms.
Spec compliance
Addresses the standing⚠️ from the previous `/spec-compliant devnet3 head` audit:
After this PR + #301, all gean histograms whose latency shape matches a spec-named bucket constant traceably reference it. The 11 hand-rolled ones are honestly hand-rolled (no spec constant covers them) and don't pretend otherwise.
Lean-review
Single subtraction-oriented pass during implementation:
Related