# leanMetrics

> Ground every observability/metrics question in leanMetrics — the authoritative standard for Prometheus-compatible metrics across Lean Ethereum consensus clients (github.com/leanEthereum/leanMetrics), always read from the latest remote main. leanMetrics fixes the metric name strings, Prometheus types, Histogram buckets, label names/enum values, and collection events that every compliant client must match; Verity's verity-metrics crate implements it. Use before implementing, reviewing, or answering anything about exposing or monitoring consensus-client metrics. Triggers: "leanMetrics", "lean_metrics", "leanMetricsを確認", "メトリクス", "metrics", "prometheus", "grafana", "observability", "観測", "dashboard", "verity-metrics", any "lean_*" metric name (e.g. "lean_head_slot", "lean_block_aggregated_payloads"), and any work exposing or monitoring consensus-client metrics in Verity. Negative triggers: Do NOT activate for consensus container shapes / fork choice / state transition behavior (use the leanSpec skill). Do NOT act

- Skill: `nyxfoundation/leanmetrics` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nyxfoundation/leanmetrics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nyxfoundation/leanmetrics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nyxfoundation (https://skillmd.com/u/nyxfoundation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nyxfoundation/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).

```bash
# 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:

| Aspect | Must match leanMetrics? |
|---|---|
| Registered metric name string (`lean_*`) | ✅ required |
| Prometheus type (Gauge/Counter/Histogram) | ✅ required |
| Histogram bucket boundaries | ✅ required (and the unit: seconds/bytes/count) |
| Label names + enum values | ✅ required |
| Internal code identifier (variable name) | ❌ 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.

| Topic (category) | leanMetrics (authoritative) | implementation reference |
|---|---|---|
| Node Info | `metrics.md#node-info-metrics` | ethlambda `crates/blockchain/src/metrics.rs`; Ream `crates/common/metrics/src/lib.rs` |
| PQ Signature | `metrics.md#pq-signature-metrics` | ethlambda `crates/blockchain/src/metrics.rs`; Ream `crates/common/metrics/src/lib.rs` |
| Block Production | `metrics.md#block-production-metrics` | (all clients □ — not yet implemented anywhere) |
| Fork-Choice | `metrics.md#fork-choice-metrics` | ethlambda / Ream metrics crates (as above) |
| State Transition | `metrics.md#state-transition-metrics` | ethlambda / Ream metrics crates (as above) |
| Validator | `metrics.md#validator-metrics` | ethlambda / Ream metrics crates (as above) |
| Network | `metrics.md#network-metrics` | ethlambda / Ream metrics crates (as above) |
| Grafana dashboards | `dashboards/lean-ethereum-clients-dashboard.json` | Ream `metrics/` (compose + Grafana stack) |

## 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.