├── README.md └── metrics.md /README.md: -------------------------------------------------------------------------------- 1 | # Ethereum Beacon metrics 2 | 3 | Discussion of [beacon node metrics](metrics.md) for Prometheus. 4 | 5 | ## License 6 | 7 | All code and generated test vectors are public domain under [CC0](https://creativecommons.org/publicdomain/zero/1.0/) 8 | -------------------------------------------------------------------------------- /metrics.md: -------------------------------------------------------------------------------- 1 | # Beacon chain metrics 2 | 3 | ## Introduction 4 | 5 | This specification encodes the behavior of sampling and collection of metrics by beacon chain clients. 6 | 7 | This specification is informative, and implementations are not required to implement all recommendations. 8 | 9 | ## Metrics 10 | 11 | This section defines a set of metrics to be sampled by beacon chain clients. 12 | 13 | ### Rationale 14 | 15 | The metrics SHOULD behave under the guidelines set by the [Prometheus documentation](https://prometheus.io/docs/practices/instrumentation/#things-to-watch-out-for). 16 | 17 | ### Interop Metrics 18 | 19 | The following are the minimal metrics agreed to be conformed by the various client teams. 20 | 21 | | Name | Metric type | Usage | Sample collection event | 22 | |--------------------------------------------|-------------|-------------------------------------------------------------|----------------------| 23 | | `libp2p_peers ` | Gauge | Tracks the total number of libp2p peers | On peer add/drop | 24 | | `beacon_head_slot` | Gauge | Latest slot of the beacon chain | On fork choice | 25 | | `beacon_finalized_epoch` | Gauge | Current finalized epoch | On epoch transition | 26 | | `beacon_current_justified_epoch` | Gauge | Current justified epoch | On epoch transition | 27 | | `beacon_previous_justified_epoch` | Gauge | Current previously justified epoch | On epoch transition | 28 | | `beacon_current_active_validators` | Gauge | Current total active validators | On epoch transition | 29 | | `beacon_reorgs_total` | Counter | Total number of chain reorganizations | On fork choice | 30 | | `beacon_processed_deposits_total` | Gauge | Total number of deposits processed | On epoch transition | 31 | 32 | \* All `*_root` values are converted to signed 64-bit integers utilizing the last 8 bytes interpreted as little-endian (`int.from_bytes(root[24:32], byteorder='little', signed=True)`). 33 | ### Additional Metrics 34 | 35 | The following are proposed metrics to be added to clients. This list is _not_ stable and is subject to drastic changes, deletions, and additions. The additional metric list is being 36 | discussed, we are yet to reach consensus. Ideally we would also discuss which of these values need to be counters, guages or histograms. 37 | 38 | | Name | Metric type | Usage | Sample collection event | 39 | |----------------------------------------------|-------------|--------------------------------------------------------------------------------------|---------------------| 40 | | `beacon_current_validators` | Gauge | Number of `status="pending\|active\|exited\|withdrawable"` validators in current epoch | On epoch transition | 41 | | `beacon_previous_validators` | Gauge | Number of `status="pending\|active\|exited\|withdrawable"` validators in previous epoch | On epoch transition | 42 | | `beacon_current_live_validators` | Gauge | Number of active validators that successfully included attestation on chain for current epoch | On block | 43 | | `beacon_previous_live_validators` | Gauge | Number of active validators that successfully included attestation on chain for previous epoch | On block | 44 | | `beacon_pending_deposits` | Gauge | Number of pending deposits (`state.eth1_data.deposit_count - state.eth1_deposit_index`) | On block | 45 | | `beacon_processed_deposits_total` | Gauge | Number of total deposits included on chain | On block | 46 | | `beacon_pending_exits` | Gauge | Number of pending voluntary exits in local operation pool | On slot | 47 | | `beacon_previous_epoch_orphaned_blocks` | Gauge | Number of blocks orphaned in the previous epoch | On epoch transition | 48 | | `gossipsub_mesh_peers_per_main_topic` | Gauge | Number of peers per gossipsub topic | On slot | 49 | | `beacon_attestation_delay_count` | Histogram | Attestation delay count, bucket size yet to be decided | On epoch transition | 50 | | `local_validator_count` | Gauge | Count of the number of local validators | On slot | 51 | | `store_beacon_block_cache_hit_total` | Gauge | Total number of block cache hits | On epoch transition | 52 | | `beacon_state_data_cache_misses_total` | Gauge | Total number of block cache misses | On epoch transition | 53 | | `beacon_head_state_finalized_root` | Gauge | Current finalized root* | On epoch transition | 54 | | `beacon_previous_justified_root` | Gauge | Current previously justified root* | On epoch transition | 55 | | `beacon_aggregates_received_total` | Gauge | Total number of aggregates received | On epoch transition | 56 | | `beacon_block_delay_count` | Histogram | Block delay count, bucket size yet to be decided | On slot | 57 | | `beacon_attestor_slashing_received_total` | Gauge | Total number of attestor slashing received | On epoch transition | 58 | | `beacon_block_proposed_total` | Gauge | Total number of blocks proposed | On epoch transition | 59 | | `beacon_attestations_published_total` | Gauge | Total number of attestations proposed | On epoch transition | 60 | | `beacon_processor_gossip_block_imported_total`| Gauge | Total number of imported blocks | On epoch transition | 61 | | `libp2p_pubsub_validation_failure_total` | Gauge | Number of pubsub validation messages failed | On epoch transition | 62 | | `beacon_head_state_root` | Gauge | Head state root | On slot | 63 | | `beacon_attestations_received_total` | Gauge | Total number of attestations received | On epoch transition | 64 | | `beacon_attestor_slashing_created_total` | Gauge | Total number of slashing created | On epoch transition | 65 | | `beacon_http_api_requests_total` | Gauge | Total number of requests to the HTTP API endpoint | On slot | 66 | | `beacon_http_api_successes_total` | Gauge | Total number of successful requests to the HTTP API endpoint | On slot | 67 | | `beacon_sync_state` | Gauge | Beacon sync state, 0 for not syncing, 1 for synced, 2 for syncing | On slot | 68 | | `process_cpu_seconds_total` | Gauge | Total CPU time in seconds | On slot | 69 | | `process_max_fds` | Gauge | Maximum number of file descriptors | On slot | 70 | 71 | 72 | ### Labels 73 | 74 | The metrics should be collected without labels unless specified. The collection process might add additional labels as metadata regarding the machine and build information. 75 | 76 | ## Prometheus metrics collection 77 | 78 | A beacon chain client using Prometheus for metrics collection SHOULD conform to the following: 79 | 80 | * Beacon chain clients SHOULD configure [Prometheus](https://prometheus.io/) so that it exposes metrics collection over an HTTP port. 81 | * Beacon chain clients MAY elect to secure the HTTP endpoint by restricting network access and applying Prometheus security settings, according to Prometheus [best practices](https://prometheus.io/docs/operating/security/). 82 | * Beacon chain clients SHOULD allow configuration flags to set the network interface and the port the Prometheus collection endpoint will be served from. 83 | * By default, the Prometheus collection endpoint SHOULD be served from 0.0.0.0:8008. 84 | --------------------------------------------------------------------------------