Skip to content
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

Add documentation for VC API /lighthouse/beacon/health #6653

Open
wants to merge 3 commits into
base: unstable
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 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
46 changes: 46 additions & 0 deletions book/src/api-vc-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
| [`POST /lighthouse/validators/mnemonic`](#post-lighthousevalidatorsmnemonic) | Create a new validator from an existing mnemonic. |
| [`POST /lighthouse/validators/web3signer`](#post-lighthousevalidatorsweb3signer) | Add web3signer validators. |
| [`GET /lighthouse/logs`](#get-lighthouselogs) | Get logs |
| [`GET /lighthouse/beacon/health`](#get-lighthousebeaconhealth) | Get health information for each connected beacon node. |

The query to Lighthouse API endpoints requires authorization, see [Authorization Header](./api-vc-auth-header.md).

Expand Down Expand Up @@ -816,3 +817,48 @@ logs emitted are INFO level or higher.
}
}
```

## `GET /lighthouse/beacon/health`

Provides information about the sync status and execution layer health of each connected beacon node.
For more inormation about how to interpret the beacon node health, see [Fallback Health](./redundancy.md#fallback-health).

### HTTP Specification

| Property | Specification |
|-------------------|--------------------------------------------|
| Path | `/lighthouse/beacon/health` |
| Method | GET |
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200, 400 |

macladson marked this conversation as resolved.
Show resolved Hide resolved
### Example Response Body

```json
{
"data": {
"beacon_nodes": [
{
"index": 0,
macladson marked this conversation as resolved.
Show resolved Hide resolved
"endpoint": "http://localhost:5052",
"health": {
"user_index": 0,
"head": 10500000,
"optimistic_status": "No",
"execution_status": "Healthy",
"health_tier": {
"tier": 1,
"sync_distance": 0,
"distance_tier": "Synced"
}
}
},
{
"index": 1,
"endpoint": "http://fallbacks-r.us",
"health": "Offline"
}
]
}
}
```
19 changes: 16 additions & 3 deletions book/src/redundancy.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,6 @@ There are a few interesting properties about the list of `--beacon-nodes`:
earlier in the list.
- *Synced is preferred*: the validator client prefers a synced beacon node over
one that is still syncing.
- *Failure is sticky*: if a beacon node fails, it will be flagged as offline
and won't be retried again for the rest of the slot (12 seconds). This helps prevent the impact
of time-outs and other lengthy errors.

> Note: When supplying multiple beacon nodes the `http://localhost:5052` address must be explicitly
> provided (if it is desired). It will only be used as default if no `--beacon-nodes` flag is
Expand Down Expand Up @@ -76,6 +73,22 @@ Prior to v3.2.0 fallback beacon nodes also required the `--subscribe-all-subnets
now broadcast subscriptions to all connected beacon nodes by default. This broadcast behaviour
can be disabled using the `--broadcast none` flag for `lighthouse vc`.

### Fallback Health

Since v6.0.0, the validator client will be more aggressive in switching to a fallback node. To do this,
it uses the concept of "Health". Every slot, the validator client checks each connected beacon node
to determine which node is the "Healthiest". In general, the validator client will prefer nodes
macladson marked this conversation as resolved.
Show resolved Hide resolved
which are synced, have synced execution layers and which are not currently optimisitically
syncing.

Sync distance is separated out into 4 tiers: "Synced", "Small", "Medium", "Large". Nodes are then
sorted into tiers based onto sync distance and execution layer status. You can use the
`--beacon-nodes-sync-tolerances` to change how many slots wide each tier is. In the case where
multiple nodes fall into the same tier, user order is used to tie-break.

To see health information for each connected node, you can use the
[`/lighthouse/beacon/health` API endpoint](./api-vc-endpoints.md#get-lighthousebeaconhealth).

### Broadcast modes

Since v4.6.0, the Lighthouse VC can be configured to broadcast messages to all configured beacon
Expand Down
10 changes: 5 additions & 5 deletions validator_client/http_api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -414,10 +414,10 @@ pub fn serve<T: 'static + SlotClock + Clone, E: EthSpec>(
},
);

// GET lighthouse/ui/fallback_health
let get_lighthouse_ui_fallback_health = warp::path("lighthouse")
.and(warp::path("ui"))
.and(warp::path("fallback_health"))
// GET lighthouse/beacon/health
let get_lighthouse_beacon_health = warp::path("lighthouse")
.and(warp::path("beacon"))
.and(warp::path("health"))
.and(warp::path::end())
.and(block_service_filter.clone())
.then(|block_filter: BlockService<T, E>| async move {
Expand Down Expand Up @@ -1303,7 +1303,7 @@ pub fn serve<T: 'static + SlotClock + Clone, E: EthSpec>(
.or(get_lighthouse_validators_pubkey)
.or(get_lighthouse_ui_health)
.or(get_lighthouse_ui_graffiti)
.or(get_lighthouse_ui_fallback_health)
.or(get_lighthouse_beacon_health)
.or(get_fee_recipient)
.or(get_gas_limit)
.or(get_graffiti)
Expand Down
Loading