diff --git a/docs/how-to/monitor/metrics.md b/docs/how-to/monitor/metrics.md index cd910c2..7040685 100644 --- a/docs/how-to/monitor/metrics.md +++ b/docs/how-to/monitor/metrics.md @@ -62,6 +62,43 @@ To configure Prometheus and run with Web3Signer: 5. View the [Prometheus graphical interface](#view-prometheus-graphical-interface). +## Run Prometheus with Web3Signer in push mode + +The [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option enables Prometheus polling of Besu, but sometimes metrics are hard to poll (for example, when running inside Docker containers with varying IP addresses). To enable Besu to push metrics to a [Prometheus push gateway](https://github.com/prometheus/pushgateway), use the [`--metrics-push-enabled`](../../reference/cli/options.md#metrics-push-enabled) option. + +To configure Prometheus and run with Web3Signer pushing to a push gateway: + +1. Configure Prometheus to read from a push gateway. For example, add the following YAML fragment to the `scrape_configs` block of the `prometheus.yml` file: + + ```yml + - job_name: push-gateway + metrics_path: /metrics + scheme: http + static_configs: + - targets: + - localhost:9091 + ``` + +1. Start the push gateway. You can deploy the push gateway using the Docker image: + + ```bash + docker pull prom/pushgateway + docker run -d -p 9091:9091 prom/pushgateway + ``` + +1. Start Web3Signer specifying options: + * [`--metrics-push-enabled`](../../reference/cli/options.md#metrics-push-enabled) + * [`--metrics-push-port`](../../reference/cli/options.md#metrics-push-enabled) + * [`--metrics-push-host`](../../reference/cli/options.md#metrics-push-host) + +1. In another terminal, run Prometheus specifying the `prometheus.yml` file: + + ```bash + prometheus --config.file=prometheus.yml + ``` + +1. View the [Prometheus graphical interface](#view-prometheus-graphical-interface). + ## View Prometheus graphical interface 1. Open a web browser to `http://localhost:9090` to view the Prometheus graphical interface. diff --git a/docs/reference/cli/options.md b/docs/reference/cli/options.md index 5c0c687..1507e8b 100644 --- a/docs/reference/cli/options.md +++ b/docs/reference/cli/options.md @@ -536,6 +536,175 @@ To allow all hostnames, use `"*"`. We don't recommend allowing all hostnames for production environments. ::: +### `metrics-push-enabled` + + + +# Syntax + +```bash +--metrics-push-enabled[=] +``` + +# Example + +```bash +--metrics-push-enabled=true +``` + +# Environment variable + +```bash +WEB3SIGNER_METRICS_PUSH_ENABLED=true +``` + +# Configuration file + +```bash +metrics-push-enabled=true +``` + + + +Enables or disables [push gateway integration](../../how-to/monitor/metrics.md#run-prometheus-with-web3signer-in-push-mode). + +You can't specify `--metrics-push-enabled` with [`--metrics-enabled`](#metrics-enabled). That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once. + +### `metrics-push-host` + + + +# Syntax + +```bash +--metrics-push-host= +``` + +# Example + +```bash +--metrics-push-host=127.0.0.1 +``` + +# Environment variable + +```bash +WEB3SIGNER_METRICS_PUSH_HOST=127.0.0.1 +``` + +# Configuration file + +```bash +metrics-push-host="127.0.0.1" +``` + + + +The host of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `127.0.0.1`. The metrics server respects the [`--metrics-host-allowlist` option](#metrics-host-allowlist). + +:::note + +When pushing metrics, ensure you set `--metrics-push-host` to the machine on which the push gateway is. Generally, this is a different machine to the machine on which Web3Signer is running. + +::: + +### `metrics-push-interval` + + + +# Syntax + +```bash +--metrics-push-interval= +``` + +# Example + +```bash +--metrics-push-interval=30 +``` + +# Environment variable + +```bash +WEB3SIGNER_METRICS_PUSH_INTERVAL=30 +``` + +# Configuration file + +```bash +metrics-push-interval=30 +``` + + + +The interval, in seconds, to push metrics when in `push` mode. The default is 15. + +### `metrics-push-port` + + + +# Syntax + +```bash +--metrics-push-port= +``` + +# Example + +```bash +--metrics-push-port=6174 +``` + +# Environment variable + +```bash +WEB3SIGNER_METRICS_PUSH_PORT=6174 +``` + +# Configuration file + +```bash +metrics-push-port="6174" +``` + + + +The port (TCP) of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `9001`. + +### `metrics-push-prometheus-job` + + + +# Syntax + +```bash +--metrics-push-prometheus-job= +``` + +# Example + +```bash +--metrics-push-prometheus-job="my-custom-job" +``` + +# Environment variable + +```bash +WEB3SIGNER_METRICS_PUSH_PROMETHEUS_JOB="my-custom-job" +``` + +# Configuration file + +```bash +metrics-push-prometheus-job="my-custom-job" +``` + + + +The job name when in `push` mode. The default is `web3signer-job`. + + ### `swagger-ui-enabled` diff --git a/project-words.txt b/project-words.txt index c808d40..11ec57a 100644 --- a/project-words.txt +++ b/project-words.txt @@ -319,6 +319,7 @@ psql pubkeys pyltsyn pubkey +pushgateway qjpuv qovery quasis