Skip to content

Add committee QBFT instrumentation taxonomy and metric surface #1097

Description

@shane-moore

Goal

Add the committee QBFT instrumentation taxonomy and metric surface needed before wiring committee QBFT lifecycle observations into qbft_instance().

This is the committee equivalent of #1066, adapted for the current epbs branch where ePBS behavior is gated by Ethereum Gloas from ChainSpec.

Depends on #1094. Coordinates with #1095 and #1096.

Context / motivation

Milestone 1 split proposer QBFT lifecycle instrumentation into two steps:

Committee QBFT should follow the same split. The current qbft_manager::instrumentation classifier is reusable, but the metric surface is still proposer-specific. Before wiring committee QBFT lifecycle events, we need a committee-capable taxonomy that does not encode validator-store duty details into the QBFT manager.

This issue should use #1094 as the source of truth for committee-duty naming, phase boundaries, outcome taxonomy, low-cardinality label discipline, and the split between Anchor-owned work and Lighthouse-owned submission. If an example in this issue conflicts with #1094, #1094 should win.

Relevant current surfaces, verified against upstream/epbs:

  • QbftManager keeps separate BeaconVote and GloasBeaconVote instance maps for CommitteeInstanceId: anchor/qbft_manager/src/lib.rs:140
  • QbftManager::receive_data routes Role::Committee messages to GloasBeaconVote when spec.fork_name_at_slot(...).gloas_enabled() is true: anchor/qbft_manager/src/lib.rs:319
  • GloasBeaconVote implements QbftDecidable using Role::Committee: anchor/qbft_manager/src/lib.rs:511
  • sign_committee_attestations selects GloasBeaconVote at Ethereum Gloas and BeaconVote before Gloas: anchor/validator_store/src/lib.rs:1550
  • sign_committee_sync_committee_signatures currently still uses BeaconVote: anchor/validator_store/src/lib.rs:1410
  • The generic QBFT loop to be wired later is qbft_instance(...): anchor/qbft_manager/src/instance.rs:280
  • The existing generic round-advance classifier is in qbft_manager::instrumentation: anchor/qbft_manager/src/instrumentation.rs:20

Suggested approach

Define a committee-capable QBFT metric and tracing taxonomy without wiring the receive loop yet.

Reuse the model from #1094 for:

  • checkpoint names where they apply to QBFT lifecycle events
  • phase boundaries around qbft_start, round changes, proposal receipt, quorum events, and consensus_decided
  • outcome naming
  • low-cardinality Prometheus label rules

Reuse the existing QBFT classifier surface from #1068:

  • RoundAdvanceReason
  • RecvArmTag
  • classify_round_advance(...)
  • existing checkpoint vocabulary where it already applies

Add or refactor metric declarations so committee QBFT can later report:

  • decided round
  • total QBFT duration
  • handoff budget at QBFT start
  • outcome
  • round advances by reason

Use bounded labels that describe the QBFT consensus instance, not the validator-store caller. Suggested labels:

  • role=committee
  • data_kind=beacon_vote|gloas_beacon_vote
  • outcome=decided|max_round_timeout|channel_closed
  • reason=timeout|f_plus_1_rc|future_proposal|rc_quorum

Do not use duty_kind=attestation|sync_message inside qbft_manager metrics. Attestation and sync-message paths are distinct in validator-store spans, but at the QBFT layer they can attach to the same CommitteeInstanceId instance and should be observed as one committee consensus instance.

The taxonomy should reflect the stable model:

  • pre-Gloas committee consensus uses BeaconVote
  • Gloas committee consensus uses GloasBeaconVote
  • the Gloas boundary comes from Ethereum ChainSpec

Acceptance criteria

  • Committee QBFT has a defined metric surface for decided round, duration, handoff budget, outcome, and round advances.
  • The metric surface can distinguish BeaconVote from GloasBeaconVote using Ethereum Gloas terminology.
  • The taxonomy follows Define committee-duty observability conventions and measurement model #1094 for naming, phase boundaries, outcome taxonomy, and label discipline.
  • The taxonomy does not use attestation or sync_message as QBFT-manager labels.
  • Existing proposer taxonomy from feat(qbft_manager): add instrumentation taxonomy and metrics surface #1068 remains usable.
  • The issue leaves qbft_instance() receive-loop wiring to a follow-up issue.
  • No Lighthouse code is patched.
  • No QBFT timeout behavior changes.
  • No committee duty, partial-signature batching, or validator-store signing behavior changes.

Tests

  • Add unit coverage for any new enum/string conversion helpers.
  • If metric names or labels are refactored, add compile-time coverage through the affected modules.
  • Run make cargo-fmt-check.
  • Run the narrowest relevant checks for qbft_manager.

Notes

This issue should prepare the committee QBFT instrumentation surface only. The next issue should wire the surface into the QBFT boundary layer, analogous to #1067.

Issues are directionally correct, not prescriptive; verify symbols at PR time.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions