This is a simple API that checks the health of a vechain node by comparing the timestamp of its latest block with the current time. If the timestamp is within an acceptable tolerance setting, it is considered healthy.
The main purpose of this tool is to be used in load balancers and availability monitors, to determine whether a node is not only online, but also fully synchronized with the blockchain. Moreover, it provides a metrics endpoint that is compatible with prometheus and exposes node health information to it.
The API contains two endpoints:
-
/healthcheckused by ALB to determine whether the node is online
-
/metricsused by Prometheus to collect health metrics, such as the last block timestamp, number of seconds since last block and node health status.
You can run the application with node, or in a container using docker.
You may override the default configuration by modifying the .env file.
The URL of the node to be monitored by the healthcheck. Defaults to https://node-test.vechain.org
The port of the healthcheck API. Defaults to 11012
The amount of seconds before the healthcheck classifies the node as unhealthy. Defaults to 15
To install and run the application with node version 16.20.2, run the following commands in the root directory of the project:
cd src
npm ci
npm startThe following bash scripts are available to help you build, run and test the app locally with docker:
cd scripts
./clean.sh
./build.sh
./run.sh
./test.sh
# or simply
./all.shTo download and run the image with docker without building it:
docker run -d \
--name node-hc \
-p 11012:11012 \
-e NODE_URL=https://mainnet.vechain.org \
public.ecr.aws/vechainfoundation/node-healthcheck:latestFor more image tags, refer to our Container Registry.
To release a new version of the exporter, follow these steps:
- If you haven't done so already, enable multi-architecture builds on your system:
- Enable Docker BuildKit for multi-architecture builds by setting the environment variable in your shell profile:
export DOCKER_BUILDKIT=1 - Create Docker BuildKit builder on your system:
docker buildx create --use
- Enable Docker BuildKit for multi-architecture builds by setting the environment variable in your shell profile:
- You will also need to have the AWS CLI installed and configured with credentials for ECR through profile
prod-node-devops. - Run
./release.sh <version>to build and push the image to ECR, where<version>is the tag for the new image. - Verify that the new release was correctly pushed to the docker repository.
If you want to contribute to this project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on Github, new technologies and and their ecosystems and how to make constructive, helpful bug reports, feature requests and the noblest of all contributions: a good, clean pull request.
For more details and guidelines on how to contribute, refer to CONTRIBUTING.
We are planning to add more features to this application going forward. More details to follow and suggestions are always welcome in the form of GitHub issues.
- v1 [31-Mar-2023] Add prometheus metrics for node health
- v0 [08-Feb-2023] Implement a basic healthcheck API for nodes, based on block timestamps
This project is licensed under the MIT license.
- Project maintainer Kostas Apostolopoulos (@kgapos) - kostas.apostolopoulos@vechain.org
- Project maintainer Rishi Pal (@rishikeshpal) - rishi.pal@vechain.org
- Main contributor Fabio Rigamonti (@fabiorigam) - fabio.rigamonti@vechain.org
- Discord https://discord.com/invite/vechain #support
- Support https://support.vechain.org
Special recognition to the main contributors: