Add description to client stats properties

packages/beacon-node/src/monitoring/clientStats.ts

@@ -30,14 +30,17 @@ function createCommonStats(process: ProcessType): ClientStats {
     version: new StaticProperty({
       jsonKey: "version",
       value: CLIENT_STATS_SPEC_VERSION,
+      description: "Client Stats data specification version",
     }),
     timestamp: new DynamicProperty({
       jsonKey: "timestamp",
       provider: Date.now,
+      description: "Unix timestamp in milliseconds",
     }),
     process: new StaticProperty({
       jsonKey: "process",
       value: process,
+      description: "Process type, can be one of: validator, beaconnode, system",
     }),
   };
 }
@@ -50,16 +53,19 @@ function createProcessStats(process: ProcessType): ClientStats {
       metricName: "process_cpu_user_seconds_total",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "CPU seconds consumed by the process",
     }),
     memoryProcessBytes: new MetricProperty({
       jsonKey: "memory_process_bytes",
       metricName: "process_resident_memory_bytes",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Amount of memory in bytes allocated to the process",
     }),
     clientName: new StaticProperty({
       jsonKey: "client_name",
       value: CLIENT_NAME,
+      description: "Name of client, e.g. lodestar, prysm, lighthouse, teku, nimbus",
     }),
     clientVersion: new MetricProperty({
       jsonKey: "client_version",
@@ -72,18 +78,22 @@ function createProcessStats(process: ProcessType): ClientStats {
       jsonType: JsonType.String,
       cacheResult: true,
       defaultValue: "",
+      description: "Version of client, e.g. 1.3.0/2d0938e",
     }),
     clientBuild: new StaticProperty({
       jsonKey: "client_build",
       value: 0,
+      description: "Incrementing integer representation of build for easier comparison",
     }),
     syncEth2FallbackConfigured: new StaticProperty({
       jsonKey: "sync_eth2_fallback_configured",
       value: false,
+      description: "Whether the client has a fallback eth2 endpoint configured",
     }),
     syncEth2FallbackConnected: new StaticProperty({
       jsonKey: "sync_eth2_fallback_connected",
       value: false,
+      description: "Whether the client is currently connected to a fallback eth2 endpoint",
     }),
   };
 }
@@ -94,60 +104,70 @@ function createBeaconNodeStats(): ClientStats {
     diskBeaconChainBytesTotal: new StaticProperty({
       jsonKey: "disk_beaconchain_bytes_total",
       value: 0,
+      description: "Amount of bytes consumed on disk by the beacon node's database",
     }),
     networkLibp2pBytesTotalReceive: new MetricProperty({
       jsonKey: "network_libp2p_bytes_total_receive",
       metricName: "libp2p_data_transfer_bytes_total",
       withLabel: {name: "protocol", value: "global received"},
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Number of bytes received via libp2p traffic",
     }),
     networkLibp2pBytesTotalTransmit: new MetricProperty({
       jsonKey: "network_libp2p_bytes_total_transmit",
       metricName: "libp2p_data_transfer_bytes_total",
       withLabel: {name: "protocol", value: "global sent"},
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Number of bytes transmitted via libp2p traffic",
     }),
     networkPeersConnected: new MetricProperty({
       jsonKey: "network_peers_connected",
       metricName: "libp2p_peers",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Number of connected peers",
     }),
     syncEth1Connected: new MetricProperty({
       jsonKey: "sync_eth1_connected",
       metricName: "lodestar_execution_engine_http_client_config_urls_count",
       jsonType: JsonType.Boolean,
       defaultValue: false,
+      description: "Whether the beacon node is connected to a eth1 node",
     }),
     syncEth2Synced: new MetricProperty({
       jsonKey: "sync_eth2_synced",
       metricName: "lodestar_sync_status",
       rangeValue: 3,
       jsonType: JsonType.Boolean,
       defaultValue: true,
+      description: "Whether the beacon node is in sync with the beacon chain network",
     }),
     syncBeaconHeadSlot: new MetricProperty({
       jsonKey: "sync_beacon_head_slot",
       metricName: "beacon_head_slot",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Slot of the head block of the beacon chain",
     }),
     syncEth1FallbackConfigured: new MetricProperty({
       jsonKey: "sync_eth1_fallback_configured",
       metricName: "lodestar_execution_engine_http_client_config_urls_count",
       threshold: 2,
       jsonType: JsonType.Boolean,
       defaultValue: false,
+      description: "Whether the beacon node has a fallback eth1 endpoint configured",
     }),
     syncEth1FallbackConnected: new StaticProperty({
       jsonKey: "sync_eth1_fallback_connected",
       value: false,
+      description: "Whether the beacon node is currently connected to a fallback eth1 endpoint",
     }),
     slasherActive: new StaticProperty({
       jsonKey: "slasher_active",
       value: false,
+      description: "Whether slasher functionality is enabled",
     }),
   };
 }
@@ -160,12 +180,14 @@ function createValidatorStats(): ClientStats {
       metricName: "vc_indices_count",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Number of validator keys in use",
     }),
     validatorActive: new MetricProperty({
       jsonKey: "validator_active",
       metricName: "vc_indices_count",
       jsonType: JsonType.Number,
       defaultValue: 0,
+      description: "Number of validator keys that are currently active",
     }),
   };
 }
@@ -177,80 +199,99 @@ function createSystemStats(): ClientStats {
       jsonKey: "cpu_cores",
       provider: () => 0,
       cacheResult: true,
+      description: "Number of CPU cores available",
     }),
     cpuThreads: new DynamicProperty({
       jsonKey: "cpu_threads",
       provider: () => 0,
       cacheResult: true,
+      description: "Number of CPU threads available",
     }),
     cpuNodeSystemSecondsTotal: new DynamicProperty({
       jsonKey: "cpu_node_system_seconds_total",
       provider: () => 0,
+      description: "CPU seconds consumed by all processes",
     }),
     cpuNodeUserSecondsTotal: new DynamicProperty({
       jsonKey: "cpu_node_user_seconds_total",
       provider: () => 0,
+      description: "CPU seconds consumed by user processes",
     }),
     cpuNodeIOWaitSecondsTotal: new DynamicProperty({
       jsonKey: "cpu_node_iowait_seconds_total",
       provider: () => 0,
+      description: "CPU seconds spent in I/O wait state",
     }),
     cpuNodeIdleSecondsTotal: new DynamicProperty({
       jsonKey: "cpu_node_idle_seconds_total",
       provider: () => 0,
+      description: "CPU seconds spent in idle state",
     }),
     memoryNodeBytesTotal: new DynamicProperty({
       jsonKey: "memory_node_bytes_total",
       provider: () => 0,
       cacheResult: true,
+      description: "Total amount of memory in bytes available",
     }),
     memoryNodeBytesFree: new DynamicProperty({
       jsonKey: "memory_node_bytes_free",
       provider: () => 0,
+      description: "Amount of free memory in bytes",
     }),
     memoryNodeBytesCached: new DynamicProperty({
       jsonKey: "memory_node_bytes_cached",
       provider: () => 0,
+      description: "Amount of memory in bytes used by cache",
     }),
     memoryNodeBytesBuffers: new DynamicProperty({
       jsonKey: "memory_node_bytes_buffers",
       provider: () => 0,
+      description: "Amount of memory in bytes used by buffers",
     }),
     diskNodeBytesTotal: new DynamicProperty({
       jsonKey: "disk_node_bytes_total",
       provider: () => 0,
+      description: "Total amount of available disk space in bytes",
     }),
     diskNodeBytesFree: new DynamicProperty({
       jsonKey: "disk_node_bytes_free",
       provider: () => 0,
+      description: "Amount of free disk space in bytes",
     }),
     diskNodeIOSeconds: new DynamicProperty({
       jsonKey: "disk_node_io_seconds",
       provider: () => 0,
+      description: "Total time spent in seconds on disk I/O operations",
     }),
     diskNodeReadsTotal: new DynamicProperty({
       jsonKey: "disk_node_reads_total",
       provider: () => 0,
+      description: "Total amount of bytes read from disk",
     }),
     diskNodeWritesTotal: new DynamicProperty({
       jsonKey: "disk_node_writes_total",
       provider: () => 0,
+      description: "Total amount of bytes written to disk",
     }),
     networkNodeBytesTotalReceive: new DynamicProperty({
       jsonKey: "network_node_bytes_total_receive",
       provider: () => 0,
+      description: "Total amount of bytes received over the network",
     }),
     networkNodeBytesTotalTransmit: new DynamicProperty({
       jsonKey: "network_node_bytes_total_transmit",
       provider: () => 0,
+      description: "Total amount of bytes transmitted over the network",
     }),
     miscNodeBootTsSeconds: new DynamicProperty({
       jsonKey: "misc_node_boot_ts_seconds",
       provider: () => 0,
+      description: "Unix timestamp in seconds of boot time",
     }),
     miscOs: new DynamicProperty({
       jsonKey: "misc_os",
       provider: () => "unk",
+      description: "Operating system, can be one of: lin, win, mac, unk for unknown",
     }),
   };
 }

packages/beacon-node/src/monitoring/properties.ts

@@ -4,6 +4,8 @@ import {JsonRecord, JsonType, MetricObject, MetricValue, MetricWithGetter, Recor
 interface PropertyDefinition {
   /** Key of value to be sent to remote service */
   jsonKey: string;
+  /** Description of the property */
+  description?: string;
 }
 
 interface StaticPropertyDefinition<T extends RecordValue> extends PropertyDefinition {