From 34727518b40c082a89fa9548cdf9989f960e8474 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Mon, 1 Jul 2019 14:58:03 +1000 Subject: [PATCH 1/8] Add common metrics EIP. --- EIPS/eip-common_metrics.md | 56 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 EIPS/eip-common_metrics.md diff --git a/EIPS/eip-common_metrics.md b/EIPS/eip-common_metrics.md new file mode 100644 index 00000000000000..c4d1980499b3b5 --- /dev/null +++ b/EIPS/eip-common_metrics.md @@ -0,0 +1,56 @@ +--- +eip: +title: Common Prometheus Metrics Names for Clients +author: Adrian Sutton (@ajsutton) +discussions-to: https://ethereum-magicians.org/t/common-chain-metrics/3415/2 +status: Draft +type: Informational +created: 2019-07-01 +--- + + + +## Simple Summary + +Standarized names for common metrics Ethereum clients to use with Prometheus. + +## Abstract + +Many Ethereum clients expose a range of metrics in a format compatible with Prometheus to allow operators to monitor the client's behaviour and performance. +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. + + +## Specification + +The table below defines metrics which may be captured by Ethereum clients which expose metrics to Prometheus. Clients may expose additional metrics however these should not use the `ethereum_` prefix. + +| Name | Metric type | Definition | JSON-RPC Equivalent | +|----------------------------------|-------------|-------------------------------------------------------------------|---------------------------------------------------------------------| +| ethereum_blockchain_height | Gauge | The current height of the canonical chain | `eth_blockNumber` | +| ethereum_best_known_block_number | Gauge | The estimated highest block available | `highestBlock` of `eth_syncing` or `eth_blockNumber` if not syncing | +| ethereum_peer_count | Gauge | The current number of peers connected | `net_peerCount` | +| ethereum_peer_limit | Gauge | The maximum number of peers this node allows to connect | No equivalent | + +Note that `ethereum_best_known_block_number` always has a value. When the `eth_syncing` JSON-RPC method would return `false`, the current chain height is used. + +## Rationale + +The defined metrics are independent of Ethereum client implementation but provide sufficient information to create an overview dashboard to support monitoring a group of Ethereum nodes. + +There is a similar, though more prescriptive, specification for [beacon chain client metrics](https://github.com/ethereum/eth2.0-metrics/blob/master/metrics.md). +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. + + +## Implementation + +These metrics are currently captured by [Pantheon](http://pegays.tech) under `pantheon_` prefixed names. They will be renamed to match this EIP in the future. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 2e8c2291681304b2c8827a1f2e8e4b2cd38149f3 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Mon, 1 Jul 2019 15:22:47 +1000 Subject: [PATCH 2/8] Fix spelling error. --- EIPS/eip-common_metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-common_metrics.md b/EIPS/eip-common_metrics.md index c4d1980499b3b5..35c85573740df8 100644 --- a/EIPS/eip-common_metrics.md +++ b/EIPS/eip-common_metrics.md @@ -12,7 +12,7 @@ created: 2019-07-01 ## Simple Summary -Standarized names for common metrics Ethereum clients to use with Prometheus. +Standardized names for common metrics Ethereum clients to use with Prometheus. ## Abstract From f04459320cba7db66fc2209c65a5f68870e1dfdc Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 07:25:48 +1000 Subject: [PATCH 3/8] Assign EIP number, added more information on what Prometheus does. --- EIPS/{eip-common_metrics.md => eip-2159.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename EIPS/{eip-common_metrics.md => eip-2159.md} (96%) diff --git a/EIPS/eip-common_metrics.md b/EIPS/eip-2159.md similarity index 96% rename from EIPS/eip-common_metrics.md rename to EIPS/eip-2159.md index 35c85573740df8..3c7d24cc726349 100644 --- a/EIPS/eip-common_metrics.md +++ b/EIPS/eip-2159.md @@ -1,5 +1,5 @@ --- -eip: +eip: 2159 title: Common Prometheus Metrics Names for Clients author: Adrian Sutton (@ajsutton) discussions-to: https://ethereum-magicians.org/t/common-chain-metrics/3415/2 @@ -12,11 +12,11 @@ created: 2019-07-01 ## Simple Summary -Standardized names for common metrics Ethereum clients to use with Prometheus. +Standardized names for common metrics Ethereum clients to use with the Prometheus, a widely used monitoring and alerting solution. ## Abstract -Many Ethereum clients expose a range of metrics in a format compatible with Prometheus to allow operators to monitor the client's behaviour and performance. +Many Ethereum 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. From 681a871a512442b917f95fd2a0e1e44feefa6517 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 07:26:48 +1000 Subject: [PATCH 4/8] Add link to prometheus website for further info. --- EIPS/eip-2159.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2159.md b/EIPS/eip-2159.md index 3c7d24cc726349..342b08e703146e 100644 --- a/EIPS/eip-2159.md +++ b/EIPS/eip-2159.md @@ -12,7 +12,7 @@ created: 2019-07-01 ## Simple Summary -Standardized names for common metrics Ethereum clients to use with the Prometheus, a widely used monitoring and alerting solution. +Standardized names for common metrics Ethereum clients to use with the [Prometheus](https://prometheus.io), a widely used monitoring and alerting solution. ## Abstract From 83e034773f0cd7008d05b626e7e0ee5f22662063 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 07:39:36 +1000 Subject: [PATCH 5/8] Fix link. --- EIPS/eip-2159.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2159.md b/EIPS/eip-2159.md index 342b08e703146e..709f4a31b8b5cc 100644 --- a/EIPS/eip-2159.md +++ b/EIPS/eip-2159.md @@ -50,7 +50,7 @@ Clients may already be publishing these metrics using different names and changi ## Implementation -These metrics are currently captured by [Pantheon](http://pegays.tech) under `pantheon_` prefixed names. They will be renamed to match this EIP in the future. +These metrics are currently captured by [Pantheon](https://pegasys.tech) under `pantheon_` prefixed names. They will be renamed to match this EIP in the future. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 9dd1610f149c373535a5d0b8e5166c00a02a0247 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 08:11:57 +1000 Subject: [PATCH 6/8] Fix discussion link. --- EIPS/eip-2159.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2159.md b/EIPS/eip-2159.md index 709f4a31b8b5cc..5475a8bad6270f 100644 --- a/EIPS/eip-2159.md +++ b/EIPS/eip-2159.md @@ -2,7 +2,7 @@ eip: 2159 title: Common Prometheus Metrics Names for Clients author: Adrian Sutton (@ajsutton) -discussions-to: https://ethereum-magicians.org/t/common-chain-metrics/3415/2 +discussions-to: https://ethereum-magicians.org/t/common-chain-metrics/3415 status: Draft type: Informational created: 2019-07-01 From d044975327169232c88d6205575466fad2417d22 Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 11:34:16 +1000 Subject: [PATCH 7/8] Switch to standards track - interface instead of informational. --- EIPS/eip-2159.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-2159.md b/EIPS/eip-2159.md index 5475a8bad6270f..e2712f9e47bd5e 100644 --- a/EIPS/eip-2159.md +++ b/EIPS/eip-2159.md @@ -4,7 +4,8 @@ title: Common Prometheus Metrics Names for Clients author: Adrian Sutton (@ajsutton) discussions-to: https://ethereum-magicians.org/t/common-chain-metrics/3415 status: Draft -type: Informational +type: Standards Track +category: Interface created: 2019-07-01 --- From 478c8acd41583d3b8391ab4297b270279b0eb9eb Mon Sep 17 00:00:00 2001 From: Adrian Sutton Date: Tue, 2 Jul 2019 12:25:06 +1000 Subject: [PATCH 8/8] Add motivation. --- EIPS/eip-2159.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/EIPS/eip-2159.md b/EIPS/eip-2159.md index e2712f9e47bd5e..ae0d25c6502b6c 100644 --- a/EIPS/eip-2159.md +++ b/EIPS/eip-2159.md @@ -21,6 +21,10 @@ Many Ethereum clients expose a range of metrics in a format compatible with Prom 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