Skip to content

Commit 42a8006

Browse files
TheLastCicadaTheLastCicada
committed
docs(API): document /diagnostics system endpoints
Add a System endpoints section to the V1 and V2 RPC guides and a Diagnostics subsection in the README Developer Guide.
1 parent b1e6974 commit 42a8006

3 files changed

Lines changed: 165 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,20 @@ This script does the following:
348348

349349
A development environment for CADT assumes a synced Chia wallet running locally. [Node version manager (nvm)](https://github.com/nvm-sh/nvm) is used to switch node environments quickly. The repo contains a `.nvmrc` file that specifies the node version the CADT is expected to use and developers can do `nvm use` to switch to the version in the `.nvmrc`.
350350

351+
### Diagnostics
352+
353+
When debugging a local CADT install (wallet not reachable, DataLayer not syncing, network mismatch, low disk space), use the system-wide diagnostics endpoint. It is mounted at the server root, not under `/v1` or `/v2`:
354+
355+
```bash
356+
curl -s -H 'x-api-key: YOUR_CADT_API_KEY' http://localhost:31310/diagnostics | jq .
357+
```
358+
359+
Omit the `x-api-key` header only when `CADT_API_KEY` is not configured. The endpoint returns **403** on read-only observer nodes (`READ_ONLY=true`). It is designed to stay usable while other API routes are blocked by sync checks.
360+
361+
Lighter-weight health checks are also available: `GET /health`, `GET /v1/health`, `GET /v2/health`, and `GET /v1/health/wallet` or `GET /v2/health/wallet` for wallet-specific status.
362+
363+
See [System endpoints in the V1 RPC guide](docs/cadt_rpc_api.md#system-endpoints) and [System endpoints in the V2 RPC guide](docs/cadt_rpc_api_v2.md#system-endpoints) for request examples and response fields.
364+
351365
### Contributing
352366

353367
All branches should be created from the `develop` branch and not from `main`. All pull requests should be made against the `develop` branch unless it is a new release. The `develop` branch will be merged into the `main` branch to create a release. Automation in the CI will create the [release](https://github.com/Chia-Network/cadt/releases) and attach the installation files to it automatically whenever code is merged to `main`. Additionally, the changelog will automatically be updated in the `main` branch. Therefore, the `main` branch should always be a representation of the latest released code.

‎docs/cadt_rpc_api.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,83 @@ If using a `CADT_API_KEY` append `--header 'x-api-key: <your-api-key-here>'` to
3131

3232
For the V2 API, update and delete requests can only stage mutations for records owned by the home organization. See the V2 API guide for details on `orgUid` ownership and child-record ownership resolution.
3333

34+
## System endpoints
35+
36+
Several routes are mounted on the server root (not under `/v1` or `/v2`). They are for monitoring and troubleshooting. Unlike most API routes, they are not blocked when the wallet or DataLayer is still syncing or migrations are in progress.
37+
38+
| Endpoint | Purpose |
39+
|----------|---------|
40+
| `GET /health` | CADT process liveness; includes disk-space summary for the Chia root partition |
41+
| `GET /v1/health` | V1 API liveness (same disk-space fields as `/health`) |
42+
| `GET /v2/health` | V2 API liveness (documented in the [V2 RPC guide](/docs/cadt_rpc_api_v2.md#system-endpoints)) |
43+
| `GET /v1/health/wallet` | V1 wallet sync and pending-transaction summary |
44+
| `GET /v2/health/wallet` | V2 wallet sync and pending-transaction summary (see V2 guide) |
45+
| `GET /diagnostics` | System-wide debug snapshot (CADT, Chia, DataLayer, host) |
46+
47+
If `CADT_API_KEY` is set, these endpoints use the same global `x-api-key` check as the rest of the API.
48+
49+
<a id="diagnostics"></a>
50+
### Diagnostics snapshot (`GET /diagnostics`)
51+
52+
Returns one JSON object summarizing CADT configuration, Chia wallet/full-node/DataLayer status, DataLayer subscriptions, local Chia processes, and host CPU/memory/disk. Each major subsection may include a `status` of `ok`, `warning`, or `critical`, plus an optional `message` when attention is needed. External calls use per-section timeouts and degrade gracefully when a subsystem is down.
53+
54+
- **Not available on read-only nodes:** returns **403** when `READ_ONLY` is `true` for V1 or V2.
55+
- **Response time:** usually well under a second on a healthy install; individual probes can take up to about 10 seconds each, with a worst-case total near 30 seconds when something is wedged.
56+
57+
Request (include the header when an API key is configured):
58+
59+
```shell
60+
curl -s -H 'x-api-key: <your-api-key-here>' http://localhost:31310/diagnostics
61+
```
62+
63+
Response (top-level shape; nested fields vary with the environment):
64+
65+
```json
66+
{
67+
"timestamp": "2024-01-15T12:00:00.000Z",
68+
"cadt": {
69+
"version": "1.0.0",
70+
"configDir": "/home/user/.chia/mainnet/cadt",
71+
"v1": { "enabled": true, "readOnly": false },
72+
"v2": { "enabled": true, "readOnly": false }
73+
},
74+
"network": { "cadt": "mainnet", "chia": "mainnet", "matches": true, "status": "ok" },
75+
"chia": {
76+
"version": "2.4.0",
77+
"wallet": { "reachable": true, "synced": true },
78+
"fullNode": { "reachable": false },
79+
"datalayer": { "reachable": true, "subscriptions": [] },
80+
"runningProcesses": { "matches": [] }
81+
},
82+
"system": {
83+
"platform": "linux",
84+
"cpu": { "cores": 8 },
85+
"memory": { "percentUsed": 42 },
86+
"disk": { "percentUsed": 55 }
87+
}
88+
}
89+
```
90+
91+
<a id="v1-health-check"></a>
92+
### V1 health check (`GET /v1/health`)
93+
94+
```shell
95+
curl --location --request GET 'http://localhost:31310/v1/health' --header 'Content-Type: application/json'
96+
```
97+
98+
```json
99+
{
100+
"message": "V1 API is running",
101+
"timestamp": "2024-01-15T12:00:00.000Z",
102+
"diskSpace": {}
103+
}
104+
```
105+
34106
## Commands
35107

108+
- [System endpoints](#system-endpoints)
109+
- [Diagnostics snapshot](#diagnostics)
110+
- [V1 health check](#v1-health-check)
36111
- [`organizations`](#organizations)
37112
- [GET Examples](#get-examples)
38113
- [List all subscribed organizations](#list-all-subscribed-organizations)

‎docs/cadt_rpc_api_v2.md‎

Lines changed: 76 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,78 @@ The CADT RPC API V2 is exposed by default on port 31310. This document will give
3535

3636
If using a `CADT_API_KEY` append `--header 'x-api-key: <your-api-key-here>'` to your `curl` request.
3737

38+
## System endpoints
39+
40+
Several routes are mounted on the server root (not under `/v1` or `/v2`). They are for monitoring and troubleshooting. Unlike most API routes, they are not blocked when the wallet or DataLayer is still syncing or migrations are in progress.
41+
42+
| Endpoint | Purpose |
43+
|----------|---------|
44+
| `GET /health` | CADT process liveness; includes disk-space summary for the Chia root partition |
45+
| `GET /v1/health` | V1 API liveness (same disk-space fields as `/health`) |
46+
| `GET /v2/health` | V2 API liveness (same disk-space fields as `/health`) |
47+
| `GET /v1/health/wallet` | V1 wallet sync and pending-transaction summary |
48+
| `GET /v2/health/wallet` | V2 wallet sync and pending-transaction summary |
49+
| `GET /diagnostics` | System-wide debug snapshot (CADT, Chia, DataLayer, host) |
50+
51+
If `CADT_API_KEY` is set, these endpoints use the same global `x-api-key` check as the rest of the API.
52+
53+
<a id="diagnostics"></a>
54+
### Diagnostics snapshot (`GET /diagnostics`)
55+
56+
Returns one JSON object summarizing CADT configuration, Chia wallet/full-node/DataLayer status, DataLayer subscriptions, local Chia processes, and host CPU/memory/disk. Each major subsection may include a `status` of `ok`, `warning`, or `critical`, plus an optional `message` when attention is needed. External calls use per-section timeouts and degrade gracefully when a subsystem is down.
57+
58+
- **Not available on read-only nodes:** returns **403** when `READ_ONLY` is `true` for V1 or V2.
59+
- **Response time:** usually well under a second on a healthy install; individual probes can take up to about 10 seconds each, with a worst-case total near 30 seconds when something is wedged.
60+
61+
Request (include the header when an API key is configured):
62+
63+
```shell
64+
curl -s -H 'x-api-key: <your-api-key-here>' http://localhost:31310/diagnostics
65+
```
66+
67+
Response (top-level shape; nested fields vary with the environment):
68+
69+
```json
70+
{
71+
"timestamp": "2024-01-15T12:00:00.000Z",
72+
"cadt": {
73+
"version": "1.0.0",
74+
"configDir": "/home/user/.chia/mainnet/cadt",
75+
"v1": { "enabled": true, "readOnly": false },
76+
"v2": { "enabled": true, "readOnly": false }
77+
},
78+
"network": { "cadt": "mainnet", "chia": "mainnet", "matches": true, "status": "ok" },
79+
"chia": {
80+
"version": "2.4.0",
81+
"wallet": { "reachable": true, "synced": true },
82+
"fullNode": { "reachable": false },
83+
"datalayer": { "reachable": true, "subscriptions": [] },
84+
"runningProcesses": { "matches": [] }
85+
},
86+
"system": {
87+
"platform": "linux",
88+
"cpu": { "cores": 8 },
89+
"memory": { "percentUsed": 42 },
90+
"disk": { "percentUsed": 55 }
91+
}
92+
}
93+
```
94+
95+
<a id="health-check"></a>
96+
### V2 health check (`GET /v2/health`)
97+
98+
```shell
99+
curl --location --request GET 'http://localhost:31310/v2/health' --header 'Content-Type: application/json'
100+
```
101+
102+
```json
103+
{
104+
"message": "V2 API is running",
105+
"timestamp": "2024-01-15T12:00:00.000Z",
106+
"diskSpace": {}
107+
}
108+
```
109+
38110
### Organization Filtering
39111

40112
All GET list endpoints support the `?orgUid=` query parameter to filter records by organization:
@@ -171,6 +243,9 @@ These files use `NEW-<n>` placeholder IDs and demonstrate the expected column na
171243

172244
## Commands
173245

246+
- [System endpoints](#system-endpoints)
247+
- [Diagnostics snapshot](#diagnostics)
248+
- [V2 health check](#health-check)
174249
- [`organizations`](#organizations)
175250
- [GET Examples](#organizations-get-examples)
176251
- [List all organizations](#list-all-organizations)
@@ -481,9 +556,7 @@ These files use `NEW-<n>` placeholder IDs and demonstrate the expected column na
481556
- [Unsubscribe from filestore](#unsubscribe-from-filestore)
482557
- [DELETE Examples](#filestore-delete-examples)
483558
- [Delete file from filestore](#delete-file-from-filestore)
484-
- [`health`](#health)
485-
- [GET Examples](#health-get-examples)
486-
- [Health check](#health-check)
559+
487560
---
488561

489562
## Reference
@@ -6625,28 +6698,5 @@ Response
66256698
}
66266699
```
66276700

6628-
---
6629-
6630-
## `health`
6631-
6632-
Functionality: Health check endpoint for V2 API
6633-
6634-
<a id="health-get-examples"></a>
6635-
### GET Examples
6636-
6637-
#### Health check
6638-
6639-
Request
6640-
```shell
6641-
curl --location --request GET 'localhost:31310/v2/health' --header 'Content-Type: application/json'
6642-
```
6643-
6644-
Response
6645-
```json
6646-
{
6647-
"message": "V2 API is running",
6648-
"timestamp": "2022-03-11T05:17:55.427Z"
6649-
}
6650-
```
66516701

66526702
---

0 commit comments

Comments
 (0)