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 2 commits into
base: unstable
Choose a base branch
from

Conversation

macladson
Copy link
Member

Proposed Changes

Changes the endpoint to get fallback health information from /lighthouse/ui/fallback_health to /lighthouse/beacon/health. This more accurately describes that the endpoint is related to the connected beacon nodes and also matched the /lighthouse/beacon/update endpoint being added in #6551.

Adds documentation for both fallback health and the endpoint to the Lighthouse book.

Additional Info

I am not marking this as a breaking change since this endpoint is very new and has yet to be documented.

@macladson macladson added val-client Relates to the validator client binary docs Documentation ready-for-review The code is ready for review labels Dec 3, 2024
Copy link
Member

@chong-he chong-he left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. I have tested the endpoint too and it is working, just got a question as commented below.


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to determine which node is the "Healthiest". In general, the validator client will prefer nodes
to determine which node is the "Healthiest". In general, the validator client will prefer nodes

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A small suggestion to add the command here.

Suggested change
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET http://localhost:5062/lighthouse/beacon/health \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq

"data": {
"beacon_nodes": [
{
"index": 0,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this index refer to?

Says we have --beacon-nodes http://localhost:5052,http://localhost:5053. My understanding is user_index is the order of the endpoint set in this flag; so for endpoint 5052, user_index=0 and for endpoint 5053, user_index=1 .

Say endpoint 5052 is offline/out of sync, and endpoint 5053 is now returned first in the list in GET /lighthouse/beacon/health. Should the index for endpoint 5053 be 0 or 1 in this case? I may be misunderstood this field. I thought it represents the "current index/current rank" of the beacon node list. But I am seeing index=1 for endpoint 5053 that's now returned first in the list.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah good question. index and user_index both always refers to the user ordering from --beacon-nodes (and soon /lighthouse/beacon/update) and so will not change even if the nodes are reordered due to health. The reason why index and user_index exist twice is an artifact of their underlying Rust representation (a bit annoying, but it helps reduce complexity). I could write a custom serializer to remove it, but I don't really think it is worth it. My guess is that almost nobody will actually interact with this API directly, but I think it perhaps has some utility in Siren (where we are free to make the actual current ordering very clear.

By the way, the actual functional order of the nodes isn't explicitly listed in the health info, but it can be inferred by:

  1. Nodes are sorted by lowest tier first.
  2. In the case where more than one node shares a tier, they are then ordered based on user_index.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation! All good, I was having a misunderstanding that the index was referring to the current rank.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation ready-for-review The code is ready for review val-client Relates to the validator client binary
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants