Skip to main content

Use metrics to monitor performance

Enable the Prometheus monitoring and alerting service for Teku metrics using the --metrics-enabled option.

Install Prometheus

To use Prometheus with Teku, install the Prometheus main component. On MacOS, install with Homebrew:

brew install prometheus

Setting up and running Prometheus with Teku

To configure Prometheus and run with Teku:

  1. Configure Prometheus to poll Teku. For example, add the following YAML fragment to the scrape_configs block of the prometheus.yml file:

    Example configuration
    scrape_interval: 15s
    - job_name: "prometheus"
    - targets: ["localhost:9090"]
    - job_name: "teku-dev"
    scrape_timeout: 10s
    metrics_path: /metrics
    scheme: http
    - targets: ["localhost:8008"]
  2. Start Teku with the --metrics-enabled option. To start a node for testing with metrics enabled:

    teku --eth1-deposit-contract-address=dddddddddddddddddddddddddddddddddddddddd \
    --eth1-endpoint=http://localhost:8545 --validators-key-file=validator_keys \
    --p2p-port=9000 --rest-api-enabled=true --rest-api-docs-enabled=true \
    --metrics-enabled=true --metrics-categories=BEACON,PROCESS,LIBP2P,JVM,NETWORK,PROCESS

    To avoid DNS rebinding attacks, if running Prometheus on a different host to your Teku node (any host other than localhost), ensure you add the hostname that Prometheus uses to connect to Teku to --metrics-host-allowlist.

    For example, if Prometheus is configured to get metrics from http://teku.local:8008/metrics then teku.local has to be in --metrics-host-allowlist.

    To specify the host and port on which Prometheus accesses Teku, use the --metrics-interface and --metrics-port options. The default host and port are and 8008.

  3. In another terminal, run Prometheus specifying the prometheus.yml file:

    prometheus --config.file=prometheus.yml
  4. View the Prometheus graphical interface.


Use a log ingestion tool, such as Logstash, to parse the logs and alert you to configured anomalies.

View Prometheus graphical interface

  1. Open a web browser to http://localhost:9090 to view the Prometheus graphical interface.

  2. Choose Graph from the menu bar and click the Console tab below.

  3. From the Insert metric at cursor drop-down, select a metric such as libp2p_peers or beacon_finalized_epoch and click Execute. The values display.


    The available metrics are prefixed with the category type specified using --metrics-categories.

    The Beacon Chain metrics lists the minimum set of metrics implemented by beacon nodes.

Click the Graph tab to view the data as a time-based graph. The query string displays below the graph.

Visualize collected data

Use Grafana to visualize the collected data. See the sample Teku Grafana dashboard.