首页 > 资讯 > health: expand health check functionality with `health` package by crypto

health: expand health check functionality with `health` package by crypto

泰然健康网
2025-08-04 05:04

Problem

Health checks for many infrastructure providers such as GCP, AWS and Cloudflare require an endpoint which accepts an HTTP GET request and returns status 200 if the service is healthy.

The current mechanism to address this was last updated in 2017 (#15496) where an exception was made to return status 200 for an empty HTTP GET request as the rpc only currently accepts POST requests of type application/json.

It would be useful to expand this functionality to enable operators to define the state required to be considered healthy. Other execution clients such as Erigon and Nethermind have implemented similar solutions.

Proposed Solution

This PR seeks to add a new package called health which extends the functionality of the http server to add a /health endpoint when invoked with the --http.health flag.

When enabled an operator can set parameters using the X-GETH-HEALTHCHECK header.

Available options (these match Erigon for cross compatibility):

synced - will check if the node has completed syncing min_peer_count<count> - will check that the node has at least <count> many peers check_block<block> - will check that the node is at least ahead of the <block> specified max_seconds_behind<seconds> - will check that the node is no more than <seconds> behind from its latest block

The request will return:

Status 200 if all of the specified parameters are met Status 500 if one or more parameters is not met or invalid A response body containing the status of each check

When no value is provided for an option that check will not run. The status of the check will be DISABLED in the return object.

Example Request

curl --request GET 'http://localhost:8545/health' --header 'X-GETH-HEALTHCHECK: min_peer_count10' --header 'X-GETH-HEALTHCHECK: synced' --header 'X-GETH-HEALTHCHECK: max_seconds_behind60'

Alternatively you can send a POST request using the same parameters in JSON:

curl --request POST http://localhost:8545/health --data '{"min_peer_count": 10, "synced": true, "max_seconds_behind": 60}'

Example Healthy Response (Status: 200)

{ "query": "OK", "check_block":"DISABLED", "max_seconds_behind":"OK", "min_peer_count":"OK", "synced":"OK" }

Example Unhealthy Response (Status: 500)

{ "query": "OK", "check_block":"DISABLED", "max_seconds_behind":"OK", "min_peer_count":"not enough peers: 2 (minimum 10)", "synced":"OK" }

Structure

Due to the restriction on the rpc package only accepting POST requests of type application/json and issues with circular imports creating a separate package which can be enabled independently appeared to be the cleanest solution. The package is similar in implementation to the graphql package in that it extends the http server, so the new package is mimicking the structure of this package.