Skip to content

Commit

Permalink
Update health api
Browse files Browse the repository at this point in the history 
Signed-off-by: Ashutosh Tripathi <[email protected]>
  • Loading branch information
@ashucoder9
ashucoder9 authored Nov 21, 2024
1 parent 4931258 commit b7ab3af
Showing 1 changed file with 51 additions and 74 deletions.
125 changes: 51 additions & 74 deletions api/health/service.md
View file
Original file line number Diff line number Diff line change
@@ -1,64 +1,47 @@
---
tags: [AvalancheGo APIs]
title: Health API
description: This page is an overview of the Health API associated with AvalancheGo. This API can be used for measuring node health.
sidebar_label: Health API
pagination_label: Health API
---

# Health API
<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
This page was generated by a plugin that directly references this [file](https://github.com/ava-labs/avalanchego/tree/master/api/health/service.md) in the AvalancheGo GitHub repository.
</Callout>

This API can be used for measuring node health.

:::info

This API set is for a specific node; it is unavailable on the [public server](/tooling/rpc-providers.md).

:::
<Callout title="Note">
This API set is for a specific node; it is unavailable on the [public server](/tooling/rpc-providers).
</Callout>

## Health Checks

The node periodically runs all health checks, including health checks for each chain.

The frequency at which health checks are run can be specified with the [--health-check-frequency](/nodes/configure/avalanchego-config-flags.md) flag.
The frequency at which health checks are run can be specified with the [\--health-check-frequency](/nodes/configure/configs-flags) flag.

## Filterable Health Checks

The health checks that are run by the node are filterable. You can specify which health checks
you want to see by using `tags` filters. Returned results will only include health checks that
match the specified tags and global health checks like `network`, `database` etc.
When filtered, the returned results will not show the full node health,
but only a subset of filtered health checks.
This means the node can still be unhealthy in unfiltered checks, even if the returned results show that the node is healthy.
AvalancheGo supports using subnetIDs as tags.
The health checks that are run by the node are filterable. You can specify which health checks you want to see by using `tags` filters. Returned results will only include health checks that match the specified tags and global health checks like `network`, `database` etc. When filtered, the returned results will not show the full node health, but only a subset of filtered health checks. This means the node can still be unhealthy in unfiltered checks, even if the returned results show that the node is healthy. AvalancheGo supports using subnetIDs as tags.

## GET Request

To get an HTTP status code response that indicates the node’s health, make a `GET` request.
If the node is healthy, it will return a `200` status code.
If the node is unhealthy, it will return a `503` status code.
In-depth information about the node's health is included in the response body.
To get an HTTP status code response that indicates the node's health, make a `GET` request. If the node is healthy, it will return a `200` status code. If the node is unhealthy, it will return a `503` status code. In-depth information about the node's health is included in the response body.

### Filtering

To filter GET health checks, add a `tag` query parameter to the request.
The `tag` parameter is a string.
For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`,
use the following query:
To filter GET health checks, add a `tag` query parameter to the request. The `tag` parameter is a string. For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`, use the following query:

```sh
```
curl 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL'
```

In this example returned results will contain global health checks and health checks that are
related to subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`.
In this example returned results will contain global health checks and health checks that are related to subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`.

**Note:** This filtering can show healthy results even if the node is unhealthy in other Chains/Subnets.
**Note**: This filtering can show healthy results even if the node is unhealthy in other Chains/Avalanche L1s.

In order to filter results by multiple tags, use multiple `tag` query parameters.
For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` and
`28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY` use the following query:
In order to filter results by multiple tags, use multiple `tag` query parameters. For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` and `28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY` use the following query:

```sh
```
curl 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL&tag=28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY'
```

Expand All @@ -68,34 +51,28 @@ The returned results will include health checks for both subnetIDs as well as gl

The available endpoints for GET requests are:

- `/ext/health` returns a holistic report of the status of the node.
**Most operators should monitor this status.**
- `/ext/health` returns a holistic report of the status of the node. **Most operators should monitor this status.**
- `/ext/health/health` is the same as `/ext/health`.
- `/ext/health/readiness` returns healthy once the node has finished initializing.
- `/ext/health/liveness` returns healthy once the endpoint is available.

## JSON RPC Request

### Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](/reference/standards/guides/issuing-api-calls.md).
### Format[​]

### Endpoint
This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see [here](/api-reference/standards/guides/issuing-api-calls).

```text
/ext/health
```
### Endpoint[​]

### Methods
### Methods[​]

#### `health.health`
#### `health.health`[​]

This method returns the last set of health check results.

**Example Call:**
**Example Call**:

```sh
```
curl -H 'Content-Type: application/json' --data '{
"jsonrpc":"2.0",
"id" :1,
Expand All @@ -106,9 +83,9 @@ curl -H 'Content-Type: application/json' --data '{
}' 'http://localhost:9650/ext/health'
```

**Example Response:**
**Example Response**:

```json
```
{
"jsonrpc": "2.0",
"result": {
Expand Down Expand Up @@ -210,24 +187,24 @@ curl -H 'Content-Type: application/json' --data '{

In this example response, every check has passed. So, the node is healthy.

**Response Explanation:**
**Response Explanation**:

- `checks` is a list of health check responses.
- A check response may include a `message` with additional context.
- A check response may include an `error` describing why the check failed.
- `timestamp` is the timestamp of the last health check.
- `duration` is the execution duration of the last health check, in nanoseconds.
- `contiguousFailures` is the number of times in a row this check failed.
- `timeOfFirstFailure` is the time this check first failed.
- A check response may include a `message` with additional context.
- A check response may include an `error` describing why the check failed.
- `timestamp` is the timestamp of the last health check.
- `duration` is the execution duration of the last health check, in nanoseconds.
- `contiguousFailures` is the number of times in a row this check failed.
- `timeOfFirstFailure` is the time this check first failed.
- `healthy` is true all the health checks are passing.

#### `health.readiness`
#### `health.readiness`[​]

This method returns the last evaluation of the startup health check results.

**Example Call:**
**Example Call**:

```sh
```
curl -H 'Content-Type: application/json' --data '{
"jsonrpc":"2.0",
"id" :1,
Expand All @@ -238,9 +215,9 @@ curl -H 'Content-Type: application/json' --data '{
}' 'http://localhost:9650/ext/health'
```

**Example Response:**
**Example Response**:

```json
```
{
"jsonrpc": "2.0",
"result": {
Expand All @@ -259,34 +236,34 @@ curl -H 'Content-Type: application/json' --data '{

In this example response, every check has passed. So, the node has finished the startup process.

**Response Explanation:**
**Response Explanation**:

- `checks` is a list of health check responses.
- A check response may include a `message` with additional context.
- A check response may include an `error` describing why the check failed.
- `timestamp` is the timestamp of the last health check.
- `duration` is the execution duration of the last health check, in nanoseconds.
- `contiguousFailures` is the number of times in a row this check failed.
- `timeOfFirstFailure` is the time this check first failed.
- A check response may include a `message` with additional context.
- A check response may include an `error` describing why the check failed.
- `timestamp` is the timestamp of the last health check.
- `duration` is the execution duration of the last health check, in nanoseconds.
- `contiguousFailures` is the number of times in a row this check failed.
- `timeOfFirstFailure` is the time this check first failed.
- `healthy` is true all the health checks are passing.

#### `health.liveness`
#### `health.liveness`[​]

This method returns healthy.

**Example Call:**
**Example Call**:

```sh
```
curl -H 'Content-Type: application/json' --data '{
"jsonrpc":"2.0",
"id" :1,
"method" :"health.liveness"
}' 'http://localhost:9650/ext/health'
```

**Example Response:**
**Example Response**:

```json
```
{
"jsonrpc": "2.0",
"result": {
Expand All @@ -299,7 +276,7 @@ curl -H 'Content-Type: application/json' --data '{

In this example response, the node was able to handle the request and mark the service as healthy.

**Response Explanation:**
**Response Explanation**:

- `checks` is an empty list.
- `healthy` is true.

0 comments on commit b7ab3af

Please sign in to comment.