leanMetrics

leanMetrics — source of truth for observability metrics

leanMetrics (github.com/leanEthereum/leanMetrics) is the authoritative standard for Prometheus-compatible metrics across all Lean Ethereum consensus clients. It is a specification (metrics.md) + Grafana dashboards (dashboards/) — not a library. It fixes what every compliant client must expose so that one dashboard serves all clients. Verity's verity-metrics crate implements it.

0. Core principle

• leanMetrics governs the exposed contract: the metric name string (lean_*), the Prometheus type (Gauge/Counter/Histogram), the Histogram bucket boundaries, the label names + enum values, and the "Sample collection event" (where the client updates the metric). A compliant client matches these exactly — that match is the entire point: it lets a single Grafana dashboard work across every client.
• It is an interop / observability standard, NOT consensus-critical (unlike leanSpec). A wrong metric breaks dashboards, not the chain.
• Internal code identifiers are free; only the registered string + type + buckets + labels are governed. (Proof: ethlambda names its variable LEAN_HEAD_SLOT, Ream names its HEAD_SLOT, and both register the same string "lean_head_slot".)
• The repo holds metrics.md (the spec table) and dashboards/ (Grafana JSON) — no client instrumentation code. "Implementing leanMetrics" means writing matching Prometheus instrumentation in the client; "using the dashboards" means pointing Grafana at any compliant client.

1. Always read leanMetrics from the remote main (no local path assumptions)

leanMetrics evolves as clients add metrics. A stale local checkout is not the standard. Read the latest main of the canonical upstream directly from the remote — this works for every developer and in CI, with no dependency on anyone's local clone.

Repo: github.com/leanEthereum/leanMetrics (canonical; do not use a personal fork).

# Latest main commit — cite this SHA in your output:
gh api repos/leanEthereum/leanMetrics/commits/main --jq '.sha'

# Read the spec table at main:
gh api "repos/leanEthereum/leanMetrics/contents/metrics.md?ref=main" --jq '.content' | base64 -d
# raw fallback (no gh):
curl -s https://raw.githubusercontent.com/leanEthereum/leanMetrics/main/metrics.md

# List the dashboards at main:
gh api "repos/leanEthereum/leanMetrics/contents/dashboards?ref=main" --jq '.[].name'
# Full tree:
gh api "repos/leanEthereum/leanMetrics/git/trees/main?recursive=1" --jq '.tree[].path'

No gh/curl? Use WebFetch on https://github.com/leanEthereum/leanMetrics/blob/main/<path>.

If you happen to have a local clone, you may use it for fast navigation/grep — but git fetch origin first and read origin/main (clones drift onto feature branches and forks). Never assume a specific clone path.

2. What the spec defines per metric

metrics.md is a set of tables, one per category. Each row defines a metric via these columns:

• Name — the exact lean_* string to register.
• Type — Gauge | Counter | Histogram.
• Usage — what it measures (use as the metric HELP text).
• Sample collection event — when the client updates it (e.g. "On state transition", "On block production", "On scrape"). This tells you where to instrument.
• Labels — label names and their allowed enum values (e.g. result=success,error).
• Buckets — for Histograms, the exact bucket boundaries (seconds, bytes, or counts).
• Per-client status — one column per tracked client.

Status legend: ✅ implemented / 📝 in progress / □ not implemented.

Tracked clients (status columns): EthLambda, Grandine, Lantern, Lighthouse, Nlean, Peam, Qlean, Ream, Zeam.

What must match the spec vs what is free:

3. Topic → authoritative location map

Paths are relative to the leanMetrics repo root, read at main. The implementation column points at Rust references only (how clients have instrumented these) — it is not authoritative for the contract.

4. How to use (implementing / reviewing / answering)

1. Read the authoritative metrics.md category section at main first.
2. Match the name string, type, Histogram buckets (and their unit), and label names + enum values exactly; internal variable names are free.
3. For coverage/status questions, read the per-client status column (✅/📝/□).
4. In your output, cite the metrics.md section + the main commit SHA you checked.

5. Relationship to leanSpec & leanVM & Verity

• leanSpec (separate skill) = consensus protocol & container shapes (Python).
• leanVM (separate skill) = aggregation + zkVM (Rust).
• leanMetrics (this skill) = the observability metric contract (Prometheus names/types/buckets/labels) + Grafana dashboards.
• Verity's verity-metrics crate implements leanMetrics; ethlambda and Ream are Rust implementation references. The client is pre-implementation today.