Skip to content

Commit beb868b

Browse files
author
Raj Karamchedu
authored
Porting NHC docs to this docs site. (#2147)
1 parent 44c7261 commit beb868b

File tree

5 files changed

+222
-185
lines changed

5 files changed

+222
-185
lines changed

‎developer-docs-site/docs/nodes/node-health-checker-faq.md

+9-8
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,29 @@
11
---
22
title: "Node Health Checker FAQ"
33
slug: "node-health-checker-faq"
4-
sidebar_position: 10
54
---
6-
import BlockQuote from "@site/src/components/BlockQuote";
75

86
# Node Health Checker FAQ
9-
The Aptos Node Health Checker (NHC) is a tool Aptos offers to the community for a few different key use cases. For now you can see more about NHC, why we have it, how to run it, and more at the [Node Health Checker README](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/node-checker) in our repo.
107

11-
The purpose of this FAQ is to help users understand why their node did not pass a particular evaluation from NHC. If you couldn't find the information you wanted in this FAQ, please [open an issue](https://github.com/aptos-labs/aptos-core/issues/new/choose) and we can add it. Even better, feel free to [open a PR](https://github.com/aptos-labs/aptos-core/pulls) and add the information yourself!
8+
The Aptos Node Health Checker (NHC) service can be used to check the health of your node(s). See [Node Health Checker](/nodes/node-health-checker) for full documentation on the NHC.
9+
10+
The purpose of this FAQ is to help you understand why your node did not pass a particular health check when you ran NHC for it. If you didn't find the information you wanted in this FAQ, [open an issue](https://github.com/aptos-labs/aptos-core/issues/new/choose), or [open a PR](https://github.com/aptos-labs/aptos-core/pulls) and add the information yourself.
1211

1312
## How does the latency evaluator work?
14-
You are likely here because you were given an evaluation result like this:
13+
14+
You are likely here because you were given an NHC evaluation result like this:
15+
1516
```
1617
Average latency too high: The average latency was 1216ms, which is higher than the maximum allowed latency of 1000ms.
1718
```
1819

19-
When faced with this error, you might see that the validation reports something like 1200ms above, but then when you `ping`, you see something more like 600ms. This difference comes from a misunderstanding in how our latency test works. When you `ping` an IP, the result you see is a single round trip (where the latency is RTT, round trip time). Our latency test is not doing an ICMP ping though, but timing a request to the API running on your node. In effect, this means we're timing 2 round trips, because it does the following:
20+
While the NHC reports 1216ms above, when you `ping` you might see a latency like 600ms. This difference is because when you `ping` an IP, the result you see is a single round trip (where the latency is the round trip time (RTT)). On the other hand, the NHC latency test will a request to the API running on your node. In effect, this means that the NHC will time 2 round trips, because it does the following:
2021

2122
1. SYN
2223
2. SYNACK
2324
3. ACK + Send HTTP request
2425
4. Receive HTTP response
2526

26-
Because we must do a TCP handshake (one round trip) and then make an HTTP request (another round trip).
27+
i.e., the NHC must do a TCP handshake (one round trip) and then make an HTTP request (second round trip).
2728

28-
The reason we have the latency evaluator is to ensure we can maintain good network performance. In particular, if the latency to your node is too high, it will result in low TPS and high time to finality, both of which are very important to running a highly performant L1 blockchain. **If you receive this error, you will need to try and improve the latency to your node, we have set high thresholds on this value with the understanding that nodes will be running all over the world**.
29+
The reason the NHC uses the latency evaluator is to ensure that we can maintain good network performance. In particular, if the latency to your node is too high, it will result in a low TPS and high time to finality, both of which are very important to running a highly performant L1 blockchain. **If you receive this error, you will need to try and improve the latency to your node. We have set high thresholds on this value with the understanding that nodes will be running all over the world**.

‎developer-docs-site/docs/nodes/node-health-checker.md

+211
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
title: "Node Health Checker"
3+
slug: "node-health-checker"
4+
---
5+
6+
# Node Health Checker
7+
8+
The Aptos Node Health Checker (NHC) service can be used to check the health of the following Aptos node types:
9+
10+
- Validator nodes.
11+
- Validator fullnodes, and
12+
- Public fullnodes.
13+
14+
If you are a node operator, use this NHC service to check if your node is running correctly. The NHC service evaluates your node's health by comparing against a baseline node configuration, and outputs the evaluation results.
15+
16+
:::tip Node health check for AIT
17+
If you are participating in the [Aptos Incentivized Testnet](/nodes/ait/ait-2), then use the NHC service to demonstrate that you can run your validator node successfully. The Aptos team uses this service continuously to check your node's health.
18+
:::
19+
20+
This document describes how to run NHC when you are operating a node.
21+
22+
## Quickstart
23+
24+
Before you get into the details of how NHC works, you can run the below steps to start the NHC service and send it a request. This quickstart uses a baseline configuration for a devnet fullnode, i.e., it will evaluate your node against a devnet fullnode that is configured with the baseline configuration YAML.
25+
26+
### Step 1: Download the baseline configuration YAML
27+
28+
Download a baseline configuration YAML file for a devnet fullnode. The below command will download the `devnet_fullnode.yaml` configuration file:
29+
30+
```
31+
mkdir /tmp/nhc && cd /tmp/nhc && wget https://raw.githubusercontent.com/aptos-labs/aptos-core/main/ecosystem/node-checker/configurations/devnet_fullnode.yaml
32+
```
33+
34+
### Step 2: Start the NHC service
35+
36+
Start the NHC service by providing the above-downloaded `devnet_fullnode.yaml` baseline configuration YAML file:
37+
38+
```
39+
docker run -v /tmp/nhc:/nhc -t aptoslabs/node-checker:nightly /usr/local/bin/aptos-node-checker server run --baseline-node-config-paths /nhc/devnet_fullnode.yaml
40+
```
41+
42+
### Step 3: Send a request to NHC service
43+
44+
Finally, send a request to the NHC service you started above. The following command runs health checks of your node that is at `node_url=http://mynode.mysite.com` and compares these results with the downloaded baseline configuration `devnet_fullnode`:
45+
46+
```
47+
curl 'http://localhost:20121/check_node?node_url=http://mynode.mysite.com&baseline_configuration_name=devnet_fullnode'
48+
```
49+
50+
You will see output similar to this:
51+
52+
```
53+
{
54+
"evaluation_results": [
55+
{
56+
"headline": "Chain ID reported by baseline and target match",
57+
"score": 100,
58+
"explanation": "The node under investigation reported the same Chain ID 18 as is reported by the baseline node",
59+
"evaluator_name": "node_identity",
60+
"category": "api",
61+
"links": []
62+
},
63+
{
64+
"headline": "Role Type reported by baseline and target match",
65+
"score": 100,
66+
"explanation": "The node under investigation reported the same Role Type full_node as is reported by the baseline node",
67+
"evaluator_name": "node_identity",
68+
"category": "api",
69+
"links": []
70+
},
71+
{
72+
"headline": "Target node produced valid recent transaction",
73+
"score": 100,
74+
"explanation": "We were able to pull the same transaction (version: 3238616) from both your node and the baseline node. Great! This implies that your node is keeping up with other nodes in the network.",
75+
"evaluator_name": "transaction_availability",
76+
"category": "api",
77+
"links": []
78+
}
79+
],
80+
"summary_score": 100,
81+
"summary_explanation": "100: Awesome!"
82+
}
83+
```
84+
85+
## How NHC works
86+
87+
The NHC runs as a service. When you want to run a health check of your node, you send the HTTP requests to this service.
88+
89+
A single NHC instance can be configured to check the health of multiple node configurations, each of different type, for example:
90+
91+
- A validator node running in a single node testnet.
92+
- A public fullnode connected to the Aptos devnet.
93+
- A validator node connected to a testnet, for example, as part of an Aptos Incentivized Testnet.
94+
95+
The NHC service can reasonably be run both as an external tool as well as a sidecar process for the operator use case. Both are described in this documentation.
96+
97+
### Baseline configuration
98+
99+
In all the above cases, a baseline node is used to compare your node's health. For example, for a public fullnode connected to the Aptos devnet, the baseline node might be a node run by the Aptos team and this node demonstrates optimal performance and participation characteristics.
100+
101+
You will download the baseline configuration YAML before running the NHC service for your node. The baseline node's configuration YAML describes where to find this baseline node (URL + port), what evaluators (e.g. metrics checks, TPS tests, API validations, etc.) the NHC service should run, what parameters the NHC should use for those evaluators, what name the configuration has, and so on. See some [example baseline configuration YAML files here](https://github.com/aptos-labs/aptos-core/tree/b183a232784e4c77991b23e8728d3c7669a95d47/ecosystem/node-checker/configuration_examples).
102+
103+
When you send requests to the NHC service, you must include a baseline configuration. For example, a request to NHC to use `devnet_fullnode` as the baseline configuration will look like this:
104+
105+
```
106+
curl 'http://nhc.aptoslabs.com/check_node?node_url=http://myfullnode.mysite.com&baseline_configuration_name=devnet_fullnode'
107+
```
108+
109+
### Getting baseline configurations ready
110+
111+
In order to run the NHC service, you must have a baseline configuration that the service can use. You have two options here:
112+
113+
#### Configure a pre-existing YAML
114+
115+
You can find a few [example baseline configuration YAML files here](https://github.com/aptos-labs/aptos-core/tree/b183a232784e4c77991b23e8728d3c7669a95d47/ecosystem/node-checker/configuration_examples) that work for each of the above use cases and more.
116+
117+
Next, download these configuration YAML files into the `/etc/nhc` folder in your host system. For example:
118+
119+
```
120+
mkdir /etc/nhc
121+
cd /etc/nhc
122+
configs=(single_node_validator devnet_fullnode ait2_validator); for c in ${configs[@]}; do wget https://raw.githubusercontent.com/aptos-labs/aptos-core/main/ecosystem/node-checker/configurations/$c.yaml; done
123+
```
124+
125+
These configurations are not quite ready to be used as they are. You will need to modify certain fields, such as the baseline node address or evaluator set (`evaluators` and `evaluator_args` in the YAML) used. The best way to iterate on this is to run the NHC with a downloaded baseline configuration and see what it says on startup.
126+
127+
#### Generate your own baseline configuration YAML
128+
129+
To generate your own baseline configuration, you must first run the NHC service with `create` option. The below command shows how to create a baseline configuration YAML by running the NHC service using Docker:
130+
131+
```
132+
docker run -it aptoslabs/node-checker:nightly /usr/local/bin/aptos-node-checker configuration create --url 'http://baseline-fullnode.aptoslabs.com' --configuration-name devnet_fullnode --configuration-name-pretty "Devnet FullNode" --evaluators network_minimum_peers api_latency --api-port 80 > /etc/nhc/devnet_fullnode.yaml
133+
```
134+
135+
The above command specifies the bare minimum for a baseline configuration. You can tune each evaluator as you see fit. See the fields `evaluators` and `evaluator_args` in the YAML. For more guidance on this, pass the `-h` flag to the above command to see all the flags you can work with.
136+
137+
### Required files
138+
139+
For some NHC configurations, you will need accompanying files, e.g. `mint.key` to use for running a TPS test against a validator. You should make sure these files are also available to NHC, either on disk or mounted into your container. NHC expects them on startup at a path specified in the baseline configuration YAML.
140+
141+
## Running NHC: Docker
142+
143+
:::tip
144+
While the Aptos team hosts our own instances of this service, we encourage the node operators to run their own instances. You may choose to either run a publicly available NHC or run it as a sidecar, where it only works against your own node.
145+
:::
146+
147+
When you are ready with baseline configuration YAML and the required files, you can run the NHC server with a command like this, for example, with Docker:
148+
149+
```
150+
docker run -v /etc/nhc:/etc/nhc -p 20121:20121 -t aptoslabs/node-checker:nightly /usr/local/bin/aptos-node-checker server run --baseline-node-config-paths /etc/nhc/ait2_validator.yaml /etc/nhc/devnet_fullnode.yaml
151+
```
152+
153+
:::tip
154+
155+
You may want to include other environment variables such as `RUST_LOG=info`. As you can see, by default NHC runs on port 20121. Make sure to publish it from the container, as shown in the above command, and ensure the port is open on your host. You may change the port NHC runs on with `--listen-port`.
156+
:::
157+
158+
## Running NHC: Source
159+
160+
First, check out the source:
161+
162+
```
163+
git clone [email protected]:aptos-labs/aptos-core.git
164+
cd aptos-core
165+
```
166+
167+
Depending on your setup, you may want to check out a particular branch, to ensure NHC is compatible with your node, e.g. `git checkout --track devnet`.
168+
169+
Run NHC:
170+
171+
```
172+
cargo run --release -- server run --baseline-node-config-paths /etc/nhc/ait2_validator.yaml /etc/nhc/devnet_fullnode.yaml
173+
```
174+
175+
176+
## Running NHC as a sidecar
177+
178+
When you run NHC as a sidecar, you preconfigure a node that NHC should use as the node under investigation by default:
179+
180+
```
181+
--target-node-url http://localhost
182+
```
183+
184+
Running NHC as a sidecar can be handy when you want to close the API / metrics ports on your machine to the public internet, but would still like to run NHC to validate the setup of your node.
185+
186+
If you want, you can even restrict NHC to test only that node:
187+
188+
```
189+
--allow-preconfigured-test-node-only
190+
```
191+
192+
With this flag, the `/check_node` endpoint will always return 400s, you must instead use `/check_preconfigured_node`.
193+
194+
Once you have configured your NHC instance in sidecar mode, you can send requests that omit the target node address.
195+
196+
```
197+
curl 'http://nhc.aptoslabs.com/check_preconfigured_node?baseline_configuration_name=devnet_fullnode'
198+
```
199+
200+
There are more options available for which ports to use. Pass `-h` to see more options.
201+
202+
## Generating the OpenAPI specs
203+
204+
To generate the OpenAPI specs, run the following commands:
205+
206+
```
207+
cargo run -- server generate-openapi -f yaml > openapi.yaml
208+
cargo run -- server generate-openapi -f json > openapi.json
209+
```
210+
211+
You can also hit the `/spec_yaml` and `/spec_json` endpoints of the running service.

‎developer-docs-site/sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ const sidebars = {
113113
],
114114
},
115115
"nodes/run-a-local-testnet",
116+
"nodes/node-health-checker",
116117
"nodes/node-health-checker-faq",
117118
],
118119
},

‎ecosystem/node-checker/DEVELOPING.md

-24
This file was deleted.

0 commit comments

Comments
 (0)