Skip to content
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
34 changes: 30 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ chain stays in memory, so the next connection syncs from its tip. A chain below
the minimum work starts again from genesis.

```sh
elo <mainnet|testnet4|signet|regtest> [<ip|name>[:port]] # IPv6 as [::1]:8333
elo [--metrics [<ip>:]<port>] <mainnet|testnet4|signet|regtest> [<ip|name>[:port]] # IPv6 as [::1]:8333
```

The peer is an IP address or a name. Before each dial, elo looks up the name
Expand All @@ -82,8 +82,9 @@ peer.

SIGTERM and SIGINT (Ctrl-C) stop elo at any step, also in the wait before a
dial. It logs the signal and exits with 0. elo exits with 1 only on a fault of
this host: its async runtime or its signal handlers do not start, a write to
stdout fails, or a read of `/dev/urandom` fails. A bug panics: elo logs the
this host: its async runtime or its signal handlers do not start, it cannot
listen on the address of `--metrics`, a write to stdout fails, or a read of
`/dev/urandom` fails. A bug panics: elo logs the
panic and exits with 101. Bad usage exits with 2.

## Log
Expand All @@ -102,6 +103,7 @@ level=info event=stop signal=SIGTERM
| --- | --- | --- |
| `version` | `info` | `peer` `version` `services` `user_agent` `start_height` `relay` |
| `tip` | `info` | `peer` `height` `hash` `work` |
| `metrics` | `info` | `address`: elo serves its metrics there |
| `end` | `warn` | `destination` `reason` `wait_ms`: elo dials again after `wait_ms`. `destination` is what the dial looked up or dialed: the peer of the command line, also a name, or the seed, such as `seed.bitcoin.sipa.be.:8333`. `peer` is always the address of a connection |
| `exit` | `error` | `reason`: a fault of this host, and elo exits with 1 |
| `stop` | `info` | `signal`: elo exits with 0 |
Expand All @@ -113,6 +115,29 @@ a `"` or a control character is in quotes, with escapes. A value is at most 260
at most 16 KiB, whatever the peer sends. When a write to stdout fails, elo writes the `exit` line to
stderr only, because the write that failed can leave part of its line on stdout.

## Metrics

With `--metrics`, elo serves its metrics at `GET /metrics`, in the Prometheus text format. A
scraper, such as Prometheus or Grafana Alloy, pulls them, and elo pushes nothing. The flag takes a
port on 127.0.0.1, or an address and a port, such as `0.0.0.0:9332` for a scraper in another
container. Port 0 takes a free port. elo logs the address in a `metrics` line before it dials.

| Metric | Type | Value |
| --- | --- | --- |
| `elo_header_tip_height` | gauge | The height of the tip of the header chain |
| `elo_header_tip_work` | gauge | The work of the chain up to the tip, in decimal |
| `elo_peer_state` | gauge | 1 for the step of the connection, and 0 for each other. The `state` label is `dial`, `sync`, `synced` or `wait` |
| `elo_reconnects_total` | counter | The connections that ended, and that elo dials again after the wait |
| `elo_metrics_failures_total` | counter | The connections to the metrics that failed. The `kind` label is `accept` for an accept error, `io` for a read or write error, `timeout` for no answer in 1 s, or `evicted` for 8 newer connections before the answer |

The tip moves when the `tip` line does: at the end of a sync, and then with each new tip. As for the
log, the names are an interface, and `src/metrics.rs` holds them. elo accepts each connection when
it comes and answers at most 8 at the same time, each in at most 1 s. It closes each connection after
its answer, and also closes a connection when 8 newer connections come before its answer, so idle
clients cannot hold a scrape. A scrape gets its answer in at most 1 s, unless 8 newer connections
come before its answer. The scrape timeout of Prometheus is 10 s by default. A request
head is at most 8 KiB. Another path gets 404, and another method gets 405.

## Build

Nix builds everything. `flake.lock` pins nixpkgs and the other inputs, and
Expand All @@ -130,7 +155,8 @@ Each push to `main` also pushes an image of elo to GHCR, as `ghcr.io/lorenzolfm/
`:sha-<commit>`. CI runs one push at a time and drops a push that waits when a newer one comes, so
a burst of merges gets an image for its last commit only. Before the push, CI runs the image against
a regtest `bitcoind` until it prints the `tip`. The arguments of the image are the arguments of
elo. It runs as user 65534 and needs no volume, no port and no writable path:
elo. It runs as user 65534 and needs no volume, no port (unless you give `--metrics`) and no
writable path:

```sh
nix build .#elo-image && docker load --input result
Expand Down
Loading