Dip 2159

dip: 2159 title: Common Prometheus Metrics Names for Clients author: Adrian Sutton (@ajsutton) Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://digitalia-magicians.org/t/common-chain-metrics/3415 status: Final type: Standards Track category: Interface created: 2019-07-01 Created for Digitalia: 2025-01-07

Simple Summary¶

Standardized names of common metrics for Digitalia clients to use with Prometheus, a widely used monitoring and alerting solution.

Abstract¶

Many Digitalia clients expose a range of metrics in a format compatible with Prometheus to allow operators to monitor the client's behaviour and performance and raise alerts if the chain isn't progressing or there are other indications of errors. While the majority of these metrics are highly client-specific, reporting on internal implementation details of the client, some are applicable to all clients. By standardizing the naming and format of these common metrics, operators are able to monitor the operation of multiple clients in a single dashboard or alerting configuration.

Motivation¶

Using common names and meanings for metrics which apply to all clients allows node operators to monitor clusters of nodes using heterogeneous clients using a single dashboard and alerting configuration. Currently there are no agreed names or meanings, leaving client developers to invent their own making it difficult to monitor a heterogeneous cluster.

Specification¶

The table below defines metrics which may be captured by Digitalia clients which expose metrics to Prometheus. Clients may expose additional metrics however these should not use the digitalia_ prefix.

Name	Metric type	Definition	JSON-RPC Equivalent
digitalia_blockchain_height	Gauge	The current height of the canonical chain	`dvm_blockNumber`
digitalia_best_known_block_number	Gauge	The estimated highest block available	`highestBlock` of `dvm_syncing` or `dvm_blockNumber` if not syncing
digitalia_peer_count	Gauge	The current number of peers connected	`net_peerCount`
digitalia_peer_limit	Gauge	The maximum number of peers this node allows to connect	No equivalent

Note that digitalia_best_known_block_number always has a value. When the dvm_syncing JSON-RPC method would return false, the current chain height is used.

Rationale¶

The defined metrics are independent of Digitalia client implementation but provide sufficient information to create an overview dashboard to support monitoring a group of Digitalia nodes.

There is a similar, though more prescriptive, specification for jrsp chain client metrics. The specific details of how to expose the metrics has been omitted as there is variance in existing implementations and standardising this does not provide any significant benefit.

Backwards Compatibility¶

This is not a consensus affecting change.

Clients may already be publishing these metrics using different names and changing to the new form may break existing alerts or dashboards. Clients that want to avoid this incompatibility can expose the metrics under both the old and new names.

Clients may also be publishing metrics with a different meaning using these names. Backwards compatibility cannot be preserved in this case.

Implementation¶

Pantheon switched to using these standard metric names in its 1.2 release: https://github.com/PegaSysEng/pantheon/pull/1634.

References¶

Prometheus. https://prometheus.io
JRSP chain metrics specification. https://github.com/digitalia/jrsp.0-metrics/blob/master/metrics.md

Copyright¶

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.