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
- Even metrics common to all clients lack an agreed name and meaning, so each development team invents its own names
- Running a mix of different clients requires building separate dashboards and alert configurations per client
- With no rule for a standard prefix, it is hard to tell which metrics are the common ones
After EIP-2159
- The names and meanings of four common metrics, chain height, highest known block number, peer count, and peer limit, are standardized
- Multiple client nodes can be monitored together with a single dashboard and alert configuration
- The ethereum_ prefix is reserved for standard common metrics only; client-specific metrics use other names
Who is affected
- Node operators: A set of nodes running different clients can be monitored with a single dashboard and alert configuration.
- Client development teams: Standard names must be adopted for common metrics. Clients that used existing names can expose both the old and new names together to preserve compatibility.
- Monitoring tool and dashboard builders: They can build dashboards and alert rules that are reusable regardless of client type.
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.