Updates

2026-07-18 16:22:56 -04:00
parent 015d92a257
commit f747ffbd25
36 changed files with 1975 additions and 873 deletions
@@ -0,0 +1,147 @@
+# REST API (Netdata-compatible)
+
+PearMonitor agents expose an optional HTTP API modeled on **Netdata Agent** endpoints (`/api/v1`, `/api/v2`, `/api/v3`).
+
+Default bind: `http://127.0.0.1:19999` (Netdata’s classic port).  
+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.
+
+## Quick examples
+
+```bash
+# Agent info
+curl -s http://127.0.0.1:19999/api/v3/info | jq
+
+# Chart catalog (v1 style)
+curl -s http://127.0.0.1:19999/api/v1/charts | jq '.charts | keys'
+
+# Last 60s of CPU (v3)
+curl -s 'http://127.0.0.1:19999/api/v3/data?chart=system.cpu&after=-60&points=60' | jq
+
+# Contexts
+curl -s http://127.0.0.1:19999/api/v3/contexts | jq
+
+# Prometheus export
+curl -s 'http://127.0.0.1:19999/api/v3/allmetrics?format=prometheus'
+
+# Health
+curl -s http://127.0.0.1:19999/api/v3/health | jq
+```
+
+## Endpoint matrix
+
+### Info & identity
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/` or `/api` | Service index + P2P pubkey |
+| GET | `/api/v1/info` | Agent info |
+| GET | `/api/v2/info` | same |
+| GET | `/api/v3/info` | **preferred** |
+| GET | `/api/v3/versions` | Agent / protocol / API versions |
+| GET | `/api/v3/me` | Anonymous REST identity note |
+| GET | `/api/v3/settings` | Runtime knobs |
+| GET | `/api/v3/config` | alias of settings |
+| GET | `/health`, `/api/v1/health`, `/api/v3/health` | Aggregate health |
+
+### Nodes
+
+| Method | Path |
+|--------|------|
+| GET | `/api/v2/nodes` |
+| GET | `/api/v3/nodes` |
+| GET | `/api/v3/node_instances` |
+| GET | `/api/v3/stream_path` |
+
+Single-agent MVP returns one node (this host). Parent/fleet aggregation is roadmap.
+
+### Contexts & charts
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/api/v3/contexts` | Context map |
+| GET | `/api/v2/contexts` | same |
+| GET | `/api/v3/context?context=` | One context |
+| GET | `/api/v1/charts` | Full chart summary (legacy but useful) |
+| GET | `/api/v1/chart?chart=` | One chart |
+
+### Data queries
+
+| Method | Path | Query params |
+|--------|------|--------------|
+| GET | `/api/v3/data` | `chart` or `context`, `after`, `before`, `points`, `group`, `tier`, `format` |
+| GET | `/api/v2/data` | same |
+| GET | `/api/v1/data` | same (legacy) |
+
+**Params (Netdata-style)**
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `chart` / `context` | required | Chart id or context id |
+| `after` | `-60` | Absolute unix sec, or relative (negative) |
+| `before` | `0` (now) | Absolute or relative |
+| `points` | `60` | Max points returned (downsampled) |
+| `group` | `average` | `average` \| `min` \| `max` \| `sum` |
+| `tier` | `0` | `0` = 1s buffer, `1` = downsampled |
+| `format` | `json` | `json` \| `csv` \| `array` |
+
+### Search & weights
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/api/v3/q?q=` | Full-text over chart ids/titles |
+| GET | `/api/v3/weights` | MVP: health-derived scores |
+
+### Alerts
+
+| Method | Path |
+|--------|------|
+| GET | `/api/v3/alerts` |
+| GET | `/api/v2/alerts` |
+| GET | `/api/v1/alarms` |
+| GET | `/api/v3/alert_transitions` |
+| GET | `/api/v3/alert_config` |
+| GET | `/api/v3/variable` |
+
+### Export & badges
+
+| Method | Path | Params |
+|--------|------|--------|
+| GET | `/api/v3/allmetrics` | `format=json\|prometheus\|shell` |
+| GET | `/api/v1/allmetrics` | same |
+| GET | `/api/v3/badge.svg` | `chart`, `dimensions`, `label` |
+
+### Functions (stub)
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/api/v3/functions` | Lists job names; execution remains P2P `runJob` for auth |
+
+## Auth model (REST)
+
+- **Default:** localhost-only, no bearer required (like a typical Netdata 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).
+
+## CORS
+
+`Access-Control-Allow-Origin` defaults to `*` (override with `PEARDATA_REST_CORS`).
+
+## Compatibility notes
+
+| Netdata | PearData MVP |
+|---------|--------------|
+| Full 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 |
+
+## Implementation
+
+- Router: `server/rest/routes.js`
+- Server: `server/rest/http-server.js`
+- Exporters: `server/rest/formatters.js`