Skip to content

docs(l1): add documentation on ethereum metrics exporter use #3538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 14, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion crates/blockchain/metrics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ To run the node with metrics, the next steps should be followed:
4. Run the docker containers, example with the L2:

```sh
docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l2.override.yaml up
docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l2.overrides.yaml up
```

> [!NOTE]
Expand Down
48 changes: 48 additions & 0 deletions docs/l1/dev-setup-l1.md
Original file line number Diff line number Diff line change
Expand Up @@ -317,3 +317,51 @@ If you want to restart the sync from the very start you can do so by wiping the
```bash
cargo run --bin ethrex -- removedb
```

## Ethereum Metrics Exporter

We use the [Ethereum Metrics Exporter](https://github.com/ethpandaops/ethereum-metrics-exporter), a Prometheus metrics exporter for Ethereum execution and consensus nodes, to gather metrics during syncing for L1. The exporter uses the prometheus data source to create a Grafana dashboard and display the metrics. For the syncing to work there must be a consensus node running along with the execution node.

Currently we have two make targets to easily start an execution node and a consensus node on either hoodi or holesky, and display the syncing metrics. In both cases we use a lighthouse consensus node.

### Quickstart guide

Make sure you have your docker daemon running.

- **Code Location**: The targets are defined in `tooling/sync/Makefile`.
- **How to Run**:

```bash
# Navigate to tooling/sync directory
cd tooling/sync

# Run target for hoodi
make start-hoodi-metrics-docker

# Run target for holesky
make start-holesky-metrics-docker
```

To see the dashboards go to [http://localhost:3001](http://localhost:3001). Use “admin” for user and password. Select the Dashboards menu and go to Ethereum Metrics Exporter (Single) to see the exported metrics.

To see the prometheus exported metrics and its respective requests with more detail in case you need to debug go to [http://localhost:9093/metrics](http://localhost:9093/metrics).

### Running the execution node on other networks with metrics enabled

A `docker-compose` is used to bundle prometheus and grafana services, the `*overrides` files define the ports and mounts the prometheus' configuration file.
If a new dashboard is designed, it can be mounted only in that `*overrides` file.
A consensus node must be running for the syncing to work.

To run the execution node on any network with metrics, the next steps should be followed:
1. Build the `ethrex` binary for the network you want (see node options in [CLI Commands](#cli-commands)) with the `metrics` feature enabled.
2. Enable metrics by using the `--metrics` flag when starting the node.
3. Set the `--metrics.port` cli arg of the ethrex binary to match the port defined in `crates/blockchain/metrics/provisioning/prometheus/prometheus_l1_sync_docker.yaml`
4. Run the docker containers:

```bash
# Navigate to crates/blockchain/metrics directory
cd crates/blockchain/metrics

docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l1.overrides.yaml up
```
For more details on running a sync go to `ethrex/tooling/sync/readme.md`.
Loading