snxraven/peardata
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Testing
Release rolling / release (push) Successful in 25s
Details
CI / test (push) Successful in 28s
Details

Browse Source
This commit is contained in:
Raven Scott
2026-07-18 16:33:43 -04:00
parent f747ffbd25
commit f7e26d1aac
53 changed files with 6491 additions and 740 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REST-API.md
+16 -15
View File
@@ -1,12 +1,12 @@
# REST API (Netdata-compatible)
# REST API (agent-compatible)
PearMonitor agents expose an optional HTTP API modeled on **Netdata Agent** endpoints (`/api/v1`, `/api/v2`, `/api/v3`).
PearMonitor agents expose an optional HTTP API for local tooling (`/api/v1`, `/api/v2`, `/api/v3`).
Default bind: `http://127.0.0.1:19999` (Netdata’s classic port).
Default bind: `http://127.0.0.1:19999`.
Disable: `PEARDATA_REST=0`.
Bind all interfaces (careful): `PEARDATA_REST_HOST=0.0.0.0`.
This is a **compatibility layer**, not a byte-for-byte Netdata clone. Core query/metadata paths are implemented for scripts, Grafana, and Prometheus scrapers.
Core query/metadata paths are implemented for scripts, Grafana, and Prometheus scrapers.
## Quick examples
@@ -36,10 +36,11 @@ curl -s http://127.0.0.1:19999/api/v3/health | jq
| Method | Path | Notes |
|--------|------|-------|
| GET | `/` or `/api` | Service index + P2P pubkey |
| GET | `/` or `/api` | Service index + P2P pubkey + HyperDB keys |
| GET | `/api/v1/info` | Agent info |
| GET | `/api/v2/info` | same |
| GET | `/api/v3/info` | **preferred** |
| GET | `/api/v3/info` | **preferred** (includes `peardata.hyperdb`) |
| GET | `/api/v3/db` | HyperDB public/discovery keys + collections |
| GET | `/api/v3/versions` | Agent / protocol / API versions |
| GET | `/api/v3/me` | Anonymous REST identity note |
| GET | `/api/v3/settings` | Runtime knobs |
@@ -75,7 +76,7 @@ Single-agent MVP returns one node (this host). Parent/fleet aggregation is roadm
| GET | `/api/v2/data` | same |
| GET | `/api/v1/data` | same (legacy) |
**Params (Netdata-style)**
**Params (agent-style)**
| Param | Default | Description |
|-------|---------|-------------|
@@ -121,7 +122,7 @@ Single-agent MVP returns one node (this host). Parent/fleet aggregation is roadm
## Auth model (REST)
- **Default:** localhost-only, no bearer required (like a typical Netdata agent bind).
- **Default:** localhost-only, no bearer required (like a typical local agent bind).
- **P2P remains the secure remote path** (Noise + roles).
- If you bind `0.0.0.0`, put REST behind a firewall, reverse proxy, or Holesail tunnel — do not expose raw metrics to the internet.
- Future: optional bearer gate (`/api/v3/bearer_protection` parity).
@@ -130,15 +131,15 @@ Single-agent MVP returns one node (this host). Parent/fleet aggregation is roadm
`Access-Control-Allow-Origin` defaults to `*` (override with `PEARDATA_REST_CORS`).
## Compatibility notes
## Scope notes
| Netdata | PearData MVP |
|---------|--------------|
| Full ML weights / metric correlations | Simplified health weights |
| Area | PearData |
|------|----------|
| ML weights / metric correlations | Simplified health weights |
| Multi-node parent streaming | Single node; parent planned |
| Cloud POST `/api/v3/spaces/.../data` | Not implemented (agent GET style only) |
| Every chart Netdata ships | Core system charts (expanding) |
| Functions execute via HTTP | Listed; run via P2P jobs |
| Cloud POST spaces APIs | Not implemented (agent GET style only) |
| App/plugin charts (nginx, DB, …) | System/OS charts; plugins later |
| Functions via HTTP | Listed; run via P2P jobs |
## Implementation