EIP-2159 Standard for common Prometheus metric names (Common Prometheus Metrics Names for Clients)

Final · Networking & nodes · EIP status Final · created 2019-07-01

Standardizes the names and meanings of four common monitoring metrics (chain height, highest known block number, peer count, and peer limit) that Ethereum clients export to Prometheus.

Why it is needed

Many Ethereum clients export metrics compatible with the Prometheus monitoring tool so that operators can watch node health. These are used to check whether the chain has stalled or shows signs of error, and to trigger alerts. However, most metrics reflect internal client implementation details, so their names vary, and even metrics common to all clients lack an agreed name and meaning. As a result, each client development team invented its own names. Node operators running a mix of different clients found it difficult to monitor everything with a single dashboard or alert configuration. This EIP standardizes the names and meanings of common metrics so that multiple kinds of nodes can be monitored on a single screen using the same criteria.

What changes

Today

After EIP-2159

Who is affected

In depth

Definition of the four standard metrics

The specification defines four metrics, all of Gauge type. ethereum_blockchain_height is the current height of the canonical chain, corresponding to the JSON-RPC eth_blockNumber. ethereum_best_known_block_number is an estimate of the highest block the node knows about, corresponding to eth_syncing's highestBlock while syncing, or to eth_blockNumber when not syncing. ethereum_peer_count is the number of currently connected peers, corresponding to net_peerCount. ethereum_peer_limit is the maximum number of peer connections this node allows; it has no corresponding JSON-RPC method.

Namespace rules and value guarantees

Clients may expose additional metrics beyond those defined in the table, but such additional metrics must not use the ethereum_ prefix. This rule reserves the standard namespace for common metrics only. Also, ethereum_best_known_block_number always has a value: when the JSON-RPC eth_syncing method would return false, i.e. when not syncing, the current chain height is used as its value. So this metric is never empty.

Design rationale

The defined metrics were chosen to provide enough information to build an overview dashboard for monitoring a group of Ethereum nodes, without being tied to any specific Ethereum client implementation. Beacon chain client metrics have a separate specification that is similar but more prescriptive. How metrics are exposed was not standardized, since existing implementations already differ in this respect and unifying it was judged to offer no meaningful benefit.

Backward compatibility

This proposal is not a consensus-affecting change. However, if a client that was already exporting the same metric under a different name switches to the new name, existing alerts or dashboards may break. Clients wishing to avoid this can expose the metric under both the old and new names. Conversely, for a client that was already using one of this standard's names with a different meaning, there is no way to preserve backward compatibility.

Implementation examples and status

The Pantheon client switched to this standard metric naming in its 1.2 release. This EIP is a Standards Track proposal in the Interface category with status Final. It covers the monitoring interface that a client exposes externally, not consensus rules. The specification is also written so that any client exposing metrics may use these names, so actual adoption depends on each client team's implementation.

Original EIP · ← EIPs