sigil-node · metrics

Source: sigil/node/sigil-node/src/metrics.rs. SHA-256: bcf1a6b4ba89d75b14520d279d1b3ead20f924a29619219019381e0f2d9e1e8d.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

metrics::REGISTRY

Global metrics registry. Cloned cheaply via Arc semantics inside prometheus::Registry; one process-wide instance is sufficient.

pub static REGISTRY: Lazy<Registry>;

Source line: 43.

metrics::CURRENT_HEIGHT

Local block height as observed by this node's persistent block store.

pub static CURRENT_HEIGHT: Lazy<IntGauge>;

Source line: 50.

metrics::HIGHEST_KNOWN_HEIGHT

Highest peer-reported height observed via libp2p block-sync.

Until Agent 05 D5 wires the peer-height path, this gauge mirrors CURRENT_HEIGHT and peer_height_available is exposed separately in sigil_getSyncStatus so consumers can detect the limitation.

pub static HIGHEST_KNOWN_HEIGHT: Lazy<IntGauge>;

Source line: 67.

metrics::SYNC_STATE

Sync state as a one-hot gauge by state label.

Exactly one of synced|syncing|halted is 1 at any moment; the others are 0. Alertmanager rules key on synced{state="halted"}.

pub static SYNC_STATE: Lazy<IntGaugeVec>;

Source line: 84.

metrics::LAST_BLOCK_TIME_SECS

Unix timestamp (seconds) of the most recent finalized block.

Set by record_block_finalized. The /health probe compares now() - LAST_BLOCK_TIME_SECS against 5 × TARGET_BLOCK_TIME_SECS to decide whether the node is healthy. 0 means no block has been finalized yet (or the engine has not booted).

pub static LAST_BLOCK_TIME_SECS: Lazy<IntGauge>;

Source line: 106.

metrics::TARGET_BLOCK_TIME_SECS

Configured target block time, in seconds, from genesis.

Set once at node startup from genesis.params.target_block_time_seconds(). Read by /health to compute the staleness tolerance window.

pub static TARGET_BLOCK_TIME_SECS: Lazy<Gauge>;

Source line: 122.

metrics::BLOCK_PRODUCTION_DURATION_SECONDS

Observed interval, in seconds, between the two most recent block timestamp updates seen by this process.

Validators update this on finalized blocks; RPC pods update it on imported blocks. It is intentionally process-local because the alert answers "is this pod seeing blocks at the expected cadence?".

pub static BLOCK_PRODUCTION_DURATION_SECONDS: Lazy<Gauge>;

Source line: 140.

metrics::BLOCKS_FINALIZED_TOTAL

Total finalized blocks since process start.

pub static BLOCKS_FINALIZED_TOTAL: Lazy<prometheus::IntCounter>;

Source line: 153.

metrics::BLOCKS_IMPORTED_TOTAL

Total blocks imported from peers via the RPC archive-sync loop.

Distinct from BLOCKS_FINALIZED_TOTAL (which the engine increments on locally-produced blocks) because RPC pods do not finalize — they import. Operators correlate this against BLOCKS_FINALIZED_TOTAL on validators to spot sync drift.

pub static BLOCKS_IMPORTED_TOTAL: Lazy<prometheus::IntCounter>;

Source line: 171.

metrics::PEER_COUNT

Number of peers the sync task observed responding successfully on the most recent tick. Zero means we are running blind.

pub static PEER_COUNT: Lazy<IntGauge>;

Source line: 185.

metrics::PEER_HEIGHT_AVAILABLE

1 once the sync task has observed at least one peer-reported height; 0 otherwise. Surfaced in sigil_getSyncStatus as peer_height_available so callers can detect the limitation without parsing free-form text.

pub static PEER_HEIGHT_AVAILABLE: Lazy<IntGauge>;

Source line: 201.

metrics::record_block_finalized

Update height gauges and the last-block timestamp.

Called once per finalized block from engine::persist_and_advance. now_secs is the unix timestamp at which the block was committed; passing it explicitly makes the operation deterministic for tests (callers in production use SystemTime::now).

pub fn record_block_finalized(height: u64, now_secs: u64);

Source line: 219.

metrics::record_block_imported

Update height gauges + counters when an RPC pod imports a block from a peer via the archive-sync loop. Distinct from record_block_finalized because the RPC sync path does NOT re-execute transactions; the executor's ExecutionState stays at genesis (this is a known Phase 1 limitation, documented in rpc_sync.rs). The sync task itself owns the SYNC_STATE label — this helper does not flip it because catching up is a process, not an event.

pub fn record_block_imported(height: u64, now_secs: u64);

Source line: 238.

metrics::init_target_block_time

Set the configured target block time at startup.

pub fn init_target_block_time(secs: f64);

Source line: 257.

metrics::block_production_staleness

Snapshot of the staleness probe used by /health.

Returns (stale, last_block_age_secs, target_block_time_seconds). stale is true if no block has been finalized in the last 5 × target_block_time_seconds. The 5-block window matches SYNC_TOLERANCE_BLOCKS_DEFAULT so /health and sigil_getSyncStatus agree on what "behind" means.

pub fn block_production_staleness(now_secs: u64) -> (bool, i64, f64);

Source line: 268.

metrics::block_production_staleness_with_fallback

Snapshot of the staleness probe with a persisted latest block timestamp fallback.

Process-local gauges start empty after restart. When a node restarts with a non-empty block store but has not finalized a fresh block yet, callers can pass the persisted tip timestamp so /health still reports a stale chain.

pub fn block_production_staleness_with_fallback(
    now_secs: u64,
    persisted_latest_block_time_secs: Option<u64>,
) -> (bool, i64, f64);

Source line: 277.

metrics::MEMPOOL_SIZE

Number of transactions currently held in the mempool.

pub static MEMPOOL_SIZE: Lazy<IntGauge>;

Source line: 299.

metrics::MEMPOOL_ADMIT_TOTAL

Mempool admission outcomes by reason.

result is enum-bounded by MempoolAdmitResult.

pub static MEMPOOL_ADMIT_TOTAL: Lazy<IntCounterVec>;

Source line: 314.

metrics::MempoolAdmitResult

Bounded set of mempool-admit results emitted by handle_send_transaction.

Adding a variant requires updating the cardinality budget in docs/launch/agent-05/DESIGN.md §2.1.

#[derive(Debug, Clone, Copy)]
pub enum MempoolAdmitResult {
    Ok,
    RejectChainId,
    RejectSignature,
    RejectMalformed,
    RejectFull,
}

Source line: 334.

metrics::MempoolAdmitResult::label

pub fn label(self) -> &'static str;

Source line: 343.

metrics::record_mempool_admit

pub fn record_mempool_admit(result: MempoolAdmitResult);

Source line: 354.

metrics::RPC_REQUEST_TOTAL

Total RPC requests by canonical method name and outcome.

method is bounded by the canonical method table in sigil-rpc::RpcMethod. result is ok|error|method_not_found.

pub static RPC_REQUEST_TOTAL: Lazy<IntCounterVec>;

Source line: 368.

metrics::RPC_REQUEST_DURATION

RPC request latency histogram by canonical method name.

pub static RPC_REQUEST_DURATION: Lazy<HistogramVec>;

Source line: 384.

metrics::RPC_REQUEST_ERRORS_TOTAL

Total RPC requests that returned an error response.

This single-series counter backs coarse production alerting. Method- level breakdown remains available via sigil_rpc_request_total.

pub static RPC_REQUEST_ERRORS_TOTAL: Lazy<prometheus::IntCounter>;

Source line: 406.

metrics::RPC_RATE_LIMITED_TOTAL

RPC requests rejected by the rate limiter (HTTP 429).

Wired by D4 hardening; exposed here so dashboards work the moment the middleware lands. Until then this counter stays at 0.

pub static RPC_RATE_LIMITED_TOTAL: Lazy<IntCounterVec>;

Source line: 422.

metrics::record_rpc

Record an RPC request outcome and elapsed duration.

method should be the canonical method name. Aliases must be normalized at the dispatch boundary so cardinality stays bounded.

pub fn record_rpc(method: &str, ok: bool, elapsed_secs: f64);

Source line: 441.

metrics::CONSENSUS_PROPOSAL_REJECT_TOTAL

Consensus proposals rejected before this validator signs a prevote.

reason must be an enum-shaped label from Agent 01's RejectedReason; never pass DIDs, hashes, or free-form error strings.

pub static CONSENSUS_PROPOSAL_REJECT_TOTAL: Lazy<IntCounterVec>;

Source line: 460.

metrics::record_consensus_proposal_reject

pub fn record_consensus_proposal_reject(reason: &'static str);

Source line: 475.

metrics::CROSS_ZONE_DELIVERY_TOTAL

Cross-zone delivery outcomes by bounded result label.

pub static CROSS_ZONE_DELIVERY_TOTAL: Lazy<IntCounterVec>;

Source line: 486.

metrics::CrossZoneDeliveryResult

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CrossZoneDeliveryResult {
    Delivered,
    Failed,
    InvalidPayload,
    SkippedInactiveZone,
}

Source line: 502.

metrics::CrossZoneDeliveryResult::label

pub fn label(self) -> &'static str;

Source line: 510.

metrics::record_cross_zone_delivery

pub fn record_cross_zone_delivery(result: CrossZoneDeliveryResult);

Source line: 520.

metrics::BUILD_INFO

Static gauge always set to 1, with build identity in labels.

version, commit, build_time are bounded — there is exactly one combination per binary.

pub static BUILD_INFO: Lazy<IntGaugeVec>;

Source line: 534.

metrics::init_build_info

Mark the build info gauge with this binary's version and commit. Call once at startup. Idempotent if called multiple times.

pub fn init_build_info(version: &str, commit: &str, build_time: &str);

Source line: 551.

metrics::set_sync_state

Set the one-hot sync-state gauge.

Sets the named state to 1 and the other two to 0 atomically (well — as atomically as three sequential set calls can be; transient double-zero windows during a state flip are acceptable for monitoring).

pub fn set_sync_state(state: SyncStateLabel);

Source line: 574.

metrics::SyncStateLabel

Bounded sync-state labels.

Halted is reserved for the case where block production has not advanced for > halt_threshold * target_block_time_seconds; wiring is owned by Agent 01's halt detector. Until then nodes flip between Synced and Syncing only.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SyncStateLabel {
    Synced,
    Syncing,
    Halted,
}

Source line: 589.

metrics::SyncStateLabel::ALL

pub const ALL: &'static [Self];

Source line: 596.

metrics::SyncStateLabel::as_str

pub fn as_str(self) -> &'static str;

Source line: 598.

metrics::render

Render the registry to Prometheus text format.

Returns the rendered body and the canonical content-type header. Errors stringify any encoder failure rather than panic so a metrics scrape never crashes the node.

pub fn render() -> Result<(String, &'static str), String>;

Source line: 616.

sigil-node · metrics

On this page