diff --git a/docs/usage/client-monitoring.md b/docs/usage/client-monitoring.md new file mode 100644 index 000000000000..f641ee1120e7 --- /dev/null +++ b/docs/usage/client-monitoring.md @@ -0,0 +1,49 @@ +# Client monitoring + +Lodestar has the ability to send client stats to a remote service for collection. +At the moment, the main service offering remote monitoring is [beaconcha.in](https://beaconcha.in/). + +Instructions for setting up client monitoring with *beaconcha.in* can be found in their docs about +[Mobile App <> Node Monitoring](https://kb.beaconcha.in/beaconcha.in-explorer/mobile-app-less-than-greater-than-beacon-node) +and in your [account settings](https://beaconcha.in/user/settings#app). + +## Configuration + +Lodestar provides CLI options to configure monitoring on both the beacon node and validator client. + +### Remote endpoint URL + +Client monitoring can be enabled by setting the `--monitoring.endpoint` flag to a remote service endpoint URL. +As monitoring relies on metrics data, it is required that metrics are also enabled by supplying the `--metrics` flag. + +```bash +lodestar beacon --monitoring.endpoint "https://beaconcha.in/api/v1/client/metrics?apikey={apikey}&machine={machineName}" --metrics +``` + +In case of *beaconcha.in*, the API key can be found in your [account settings](https://beaconcha.in/user/settings#api). +Setting the machine is optional but it is especially useful if you are monitoring multiple nodes. + + +!!! note + When sending data to a remote service you should be conscious about security: + + - Only use a service that you trust as this will send information which may identify you + and associate your validators, IP address and other personal information. + - Always use a HTTPS connection (i.e. a URL starting with `https://`) to prevent the traffic + from being intercepted in transit and leaking information. + + +More details about the data sent to the remote service can be found in the [specification](https://docs.google.com/document/d/1qPWAVRjPCENlyAjUBwGkHMvz9qLdd_6u9DPZcNxDBpc). + +It is also possible to print out the data sent to the remote service by enabling debug logs which can be done by supplying the `--logLevel debug` flag. + +### Monitoring interval + +It is possible to adjust the interval between sending client stats to the remote service by +setting the `--monitoring.interval` flag. It takes an integer value in milliseconds, the default is `60000` which means data is sent once a minute. + +```bash +lodestar beacon --monitoring.interval 60000 +``` + +Increasing the monitoring interval can be useful if you are running into rate limit errors when posting large amounts of data for multiple nodes. diff --git a/mkdocs.yml b/mkdocs.yml index 6775a5deb192..759a8dfd7151 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -76,6 +76,7 @@ nav: - Validator management: usage/validator-management.md - Prometheus & Grafana Setup: usage/prometheus-grafana.md - MEV Builder Integration: usage/mev-integration.md + - Client monitoring: usage/client-monitoring.md - Reference: - Command line: reference/cli.md - Libraries: libraries/index.md diff --git a/packages/cli/src/cmds/validator/options.ts b/packages/cli/src/cmds/validator/options.ts index 194f1386633e..b690521ee069 100644 --- a/packages/cli/src/cmds/validator/options.ts +++ b/packages/cli/src/cmds/validator/options.ts @@ -305,7 +305,6 @@ export const validatorOptions: ICliCommandOptions = { description: "Interval in milliseconds between sending client stats to the remote service", defaultDescription: String(validatorMonitoringDefaultOptions.interval), group: "monitoring", - hidden: true, }, "monitoring.initialDelay": { diff --git a/packages/cli/src/options/beaconNodeOptions/monitoring.ts b/packages/cli/src/options/beaconNodeOptions/monitoring.ts index ec649b6850fb..f0cf3fbd77b0 100644 --- a/packages/cli/src/options/beaconNodeOptions/monitoring.ts +++ b/packages/cli/src/options/beaconNodeOptions/monitoring.ts @@ -32,7 +32,6 @@ export const options: ICliCommandOptions = { description: "Interval in milliseconds between sending client stats to the remote service", defaultDescription: String(defaultOptions.monitoring.interval), group: "monitoring", - hidden: true, }, "monitoring.initialDelay": {