peardata/docs/SWAGGER_PLAN.md

Swagger / metrics compatibility plan

Plan and verification for PearData’s agent-style REST surface (/api/v1|v2|v3):

• Spec shape: OpenAPI-style path inventory — 68 paths / 72 operations used as a historical checklist (GET/POST/PUT)
• PearData router: server/rest/routes.js
• Chart catalog: shared/metrics.js + collectors under server/services/

This document answers two questions:

1. Which REST operations from that checklist does PearData implement?
2. Which metric charts / dimensions (the data those APIs serve) are collected?

Verified: 2026-07-18 (static analysis of routes + collector emit sites; unit tests 73/73).

---

Summary

Surface	Upstream	PearData	Status
OpenAPI operations	72	38 path matches + PearData-only extras	Core metrics path covered; cloud/auth/WebRTC out of scope
Host static charts	(collector-defined; not enumerated in swagger)	35 / 35 defined & emitted	Complete
Instance charts (cpu/disk/net/mount)	same	Patterns implemented in collector	Complete on Linux
Opt-in collectors	app plugins	docker / processes / nginx / redis / postgres / fleet / peardock	Complete when env-enabled
Data query (/api/v*/data)	v1–v3	v1–v3	Implemented (MVP grouping)
allmetrics export	shell / prometheus / json	shell / prometheus / json	Implemented (prometheus_all_hosts not separate)
Contexts	v1–v3	v2 + v3 (v1 missing)	Partial
Weights / search / logs	v1–v3	v1–v3 weights + logs	Done (single-host)
Alerts	rich v1–v3	core read paths	Partial
Cloud / claim / ACLK / bearer / WebRTC	many	none	Intentionally out of scope

Verdict: All core host metrics required for agent-style dashboards and scrapers are implemented. REST metric read endpoints (charts, data, allmetrics, contexts v2/v3, badges, health) are implemented. Gaps are mostly legacy v1 aliases, deep alert/config APIs, function execution over HTTP, and cloud/auth endpoints that PearData replaces with P2P + HyperDHT.

---

Part A — Metric charts (what scrapers/UI need)

Swagger describes HTTP shapes; the metric inventory lives in collectors. PearData’s target catalog (agent-compatible context IDs) is below.

A1. Host-wide static charts — verified implemented

All IDs are in STATIC_CHART_DEFS and referenced by server/services/collector.js emit paths.

Chart ID	Dimensions (key)	Units	Status
system.cpu	guest_nice, guest, steal, softirq, irq, user, system, nice, iowait, idle	percentage	done
system.intr	interrupts	interrupts/s	done
system.ctxt	switches	context switches/s	done
system.forks	started	processes/s	done
system.processes	running, blocked	processes	done
system.active_processes	active	processes	done
system.load	load1, load5, load15	load	done
system.uptime	uptime	seconds	done
system.entropy	entropy	entropy	done
system.ram	free, used, cached, buffers	MiB	done
mem.available	avail	MiB	done
mem.swap	free, used	MiB	done
mem.swap_cached	cached	MiB	done
mem.kernel	slab, kernel_stack, page_tables, vmalloc_used	MiB	done
mem.slab	reclaimable, unreclaimable	MiB	done
mem.writeback	dirty, writeback	MiB	done
mem.committed	Committed_AS	MiB	done
mem.swapio	in, out	KiB/s	done
system.pgpgio	in, out	KiB/s	done
system.pgfaults	minor, major	faults/s	done
system.io	in, out	KiB/s	done
system.net	received, sent	kilobits/s	done
system.ip	received, sent	kilobits/s	done
system.ipv6	received, sent	kilobits/s	done
ip.tcppackets	received, sent	packets/s	done
ip.tcperrors	InErrs, InCsumErrors, RetransSegs	packets/s	done
ip.tcpopens	active, passive	connections/s	done
ip.tcpsock	connections	connections	done
ipv4.packets	received, sent, forwarded, delivered	packets/s	done
ipv4.errors	InDiscards, OutDiscards, InHdrErrors, OutNoRoutes	packets/s	done
ipv4.udppackets	received, sent	packets/s	done
ipv4.udperrors	RcvbufErrors, SndbufErrors, InErrors, NoPorts	packets/s	done
system.cpu_some_pressure	some10, some60, some300	percentage	done (Linux PSI)
system.memory_some_pressure	some10, some60, some300	percentage	done (Linux PSI)
system.io_some_pressure	some10, some60, some300	percentage	done (Linux PSI)

Score: 35 / 35 static host charts implemented.

A2. Instance charts — verified implemented (runtime)

Pattern	Context	Dimensions	Status
cpu.cpu{N}	cpu.cpu	same as system.cpu	done
disk_io.{dev}	disk.io	reads, writes	done
disk_ops.{dev}	disk.ops	reads, writes	done
disk_util.{dev}	disk.util	utilization	done
net.{iface}	net.net	received, sent	done
net_packets.{iface}	net.packets	received, sent, multicast	done
net_errors.{iface}	net.errors	inbound, outbound	done
net_drops.{iface}	net.drops	inbound, outbound	done
disk_space.{mount}	disk.space	avail, used, reserved_for_root	done
disk_inodes.{mount}	disk.inodes	avail, used, reserved_for_root	done

A3. Opt-in / plugin charts — verified implemented

Env gate	Charts	Status
PEARDATA_DOCKER=1	docker.containers, docker.cpu.*, docker.mem.* (human titles via socket; installer auto-enables)	done
PEARDATA_PROCESSES=1	processes.top_cpu, processes.top_rss	done
PEARDATA_NGINX=1	nginx.connections, nginx.requests	done
PEARDATA_REDIS=1	redis.memory, redis.clients, redis.stats	done
PEARDATA_POSTGRES=1	postgres.up, postgres.stats	done
PEARDATA_PARENT=1	fleet.cpu, fleet.ram, fleet.children	done
PEARDATA_PEARDOCK=1	peardock.* (remapped)	done

A4. Metric gaps (not required by swagger paths, but common agent charts)

These appear in many agent installs but are not in PearData yet. Track as optional collector work:

Family	Examples	Priority
cgroup / systemd services	cgroup.*, systemd.service.*	P2
apps.plugin	apps.cpu, apps.mem, apps.vmem, …	P2
disk SMART / mdstat	disk_await.*, md.health	P3
wireless / wifi	wireless.*	P3
sensors / hwmon	sensors.*	P3
eBPF / softnet	softnet.*, ebpf.*	P3
Windows deep collectors	beyond os fallback CPU/RAM/load	P2 (roadmap)

---

Part B — OpenAPI endpoint matrix

Legend:

Code	Meaning
done	Path handled in routes.js with useful behavior
partial	Path exists but MVP / stub vs full upstream semantics
alias-miss	Upstream has path; PearData covers same capability on another version
skip	Out of scope (cloud, proprietary auth, deprecated)
todo	In scope for PearData; not implemented

B1. Charts & contexts (metrics catalog)

Op	Path	PearData	Notes
GET	/api/v1/charts	done	Full chart map
GET	/api/v1/chart	done	Single chart
GET	/api/v1/contexts	alias-miss	Use /api/v2|v3/contexts
GET	/api/v1/context	alias-miss	Use /api/v2|v3/context
GET	/api/v2/contexts	done
GET	/api/v3/contexts	done	Preferred
GET	/api/v3/context	done
GET	/api/v2/q	partial	Chart id/title/family search
GET	/api/v3/q	partial	Same

B2. Data & export (core metrics APIs)

Op	Path	PearData	Notes
GET	/api/v1/data	done	chart/context, after/before/points/group/tier/format
GET	/api/v2/data	partial	No full group_by / multi-node aggregation
GET	/api/v3/data	partial	Preferred; HyperDB warm fallback supported
GET	/api/v1/allmetrics	done	json | prometheus | shell
GET	/api/v2/allmetrics	done
GET	/api/v3/allmetrics	done	Preferred; prometheus_all_hosts → treat as prometheus
GET	/api/v1/badge.svg	partial	Basic SVG; limited styling params
GET	/api/v3/badge.svg	partial	Same
GET	/api/v1/variable	alias-miss	Use /api/v3/variable
GET	/api/v3/variable	partial	Alert/variable lookup MVP

B3. Weights / scoring

Op	Path	PearData	Notes
GET	/api/v1/weights	done	Same engine as v2/v3
GET	/api/v1/metric_correlations	skip	Deprecated upstream
GET	/api/v2/weights	done	MC: volume / ks2 / anomaly-rate / value; no window → alerts
GET	/api/v3/weights	done	Same; see REST-API + user-guide/weights-api. Multi-node scope_nodes / fleet aggregation still out of scope
GET	/api/v1|v2|v3/logs	done	PearData extension — anomaly / audit / journal (queryLogs); see REST-API + user-guide/logs

B4. Nodes / info / health

Op	Path	PearData	Notes
GET	/api/v1/info	done
GET	/api/v2/info	done
GET	/api/v3/info	done	Includes HyperDB metadata
GET	/api/v2/nodes	done	Single node; parent expands children
GET	/api/v3/nodes	done
GET	/api/v2/node_instances	alias-miss	Use /api/v3/node_instances
GET	/api/v3/node_instances	done
GET	/api/v2/versions	alias-miss	Use /api/v3/versions
GET	/api/v3/versions	done
GET	/api/v3/stream_path	partial	Local + parent children hops
GET	/api/v3/stream_info	todo	Streaming stats (map to parent/P2P later)
GET	/health, /api/v1/health, /api/v3/health	done	PearData extension (not all in swagger)

B5. Alerts

Op	Path	PearData	Notes
GET	/api/v1/alarms	done
GET	/api/v1/alarms_values	todo
GET	/api/v1/alarm_log	todo	Transitions ≈ /api/v3/alert_transitions
GET	/api/v1/alarm_count	todo	Derivable from alerts list
GET	/api/v1/alarm_variables	partial
GET	/api/v2/alerts	done
GET	/api/v3/alerts	done	Preferred
GET	/api/v2/alert_transitions	alias-miss	Use v3
GET	/api/v3/alert_transitions	partial	Recent anomaly events
GET	/api/v2/alert_config	alias-miss	Use v3
GET	/api/v3/alert_config	partial	List configs

B6. Functions / config / settings

Op	Path	PearData	Notes
GET	/api/v1/functions	alias-miss	Use v2/v3
GET	/api/v1/function	skip / todo	Execute via P2P runJob
GET	/api/v2/functions	partial	List only
GET	/api/v3/functions	partial	List only
GET/POST	/api/v3/function	todo	Prefer authenticated P2P
GET	/api/v2/progress	skip
GET	/api/v3/progress	todo	Only if HTTP functions land
GET	/api/v3/settings	partial	Read-only runtime knobs
PUT	/api/v3/settings	todo	GET returns retention + storage; writes use P2P admin RPC (setRetentionConfig / pruneHistory)
GET/POST	/api/v1/config	skip	DynCFG; use env + P2P
GET/POST	/api/v3/config	partial	Aliases settings GET; no DynCFG tree

B7. Auth / cloud / realtime — out of scope

Op	Path	PearData	Notes
GET	/api/v3/me	partial	Anonymous REST identity note
GET	/api/v*/bearer_*	skip	Future optional bearer
GET	/api/v*/claim	skip	Cloud claiming N/A
GET	/api/v1/aclk	skip	Cloud link N/A
GET	/api/v1/registry	skip	Deprecated
GET	/api/v1/manage/health	skip	Use P2P alert ops
GET	/api/v1/dbengine_stats	skip	Use /api/v3/db (HyperDB)
GET	/api/v1/ml_info	skip	Deprecated; anomaly via engine
POST	/api/v*/rtc_offer	skip	WebRTC N/A; use HyperDHT / tunnel

B8. PearData-only REST (not in swagger)

Op	Path	Purpose
GET	/api/v3/fleet	Parent fleet health
GET	/api/v3/export	Snapshot / prometheus write
GET	/api/v3/tunnel	HyperDHT REST tunnel status
GET	/api/v3/db	HyperDB keys + collections
GET	/, /api	Service index

---

Part C — Implementation depth checklist (metrics path)

Capability	Required by swagger consumers	PearData
List charts with dimensions	yes	done
Query time-series by chart	yes	done
Query by context	yes	done
Relative after=-60	yes	done
points + downsample	yes	done
group=average|min|max|sum	yes	done
Multi-format data (json, csv, array)	yes	done
Prometheus scrape (allmetrics)	yes	done
Badge SVG	yes	partial
Context search (/q)	yes	partial
Weights / Metric Correlations API	yes	done (single-host; no multi-node scope)
v2/v3 group_by across nodes	yes (v2+)	todo
HTTP function execute	yes	todo (P2P today)
Full DynCFG	yes	skip (env + jobs)

---

Part D — Work plan (priority)

P0 — already satisfied for metrics consumers

• Host chart catalog + Linux collectors
• /api/v1/charts, /api/v*/data, /api/v*/allmetrics
• /api/v3/contexts, health, nodes, badges (basic)

P1 — close swagger gaps that matter for tooling

1. Add v1 aliases: /api/v1/contexts, /api/v1/context, /api/v1/variable → existing handlers (/api/v1/weights already done)
2. Add v2 aliases: alert_transitions, alert_config, node_instances, versions
3. Extend allmetrics: accept format=prometheus_all_hosts as alias of prometheus; honor filter, prefix
4. Document response-field parity for Grafana/Prometheus dashboards in REST-API.md

P2 — deepen metrics APIs

1. Richer /api/v3/weights ✅ single-host MC engine (volume / ks2 / anomaly-rate / value)
2. /api/v1/alarm_count, /api/v1/alarms_values, /api/v1/alarm_log thin wrappers
3. Optional PUT /api/v3/settings (localhost-only) — today prefer P2P Data Manager RPC
4. HTTP function bridge to runJob with strict localhost/admin gate
5. /api/v3/stream_info from parent collector stats

P3 — optional collectors (not swagger-listed)

• cgroup / apps.plugin-style process trees
• sensors, SMART, md
• Windows collector depth

Explicit non-goals

• Cloud claim / ACLK / registry
• WebRTC offers
• Full DynCFG tree parity
• Bearer auth (until someone binds REST publicly)

---

Part E — How to re-verify

# 1) Diff documented REST paths against the router
rg -o '/api/v[123]/[a-zA-Z0-9_./{}-]+' docs/REST-API.md docs/SWAGGER_PLAN.md | sort -u > /tmp/doc-paths.txt
rg -o '/api/v[123]/[a-zA-Z0-9_./-]+' server/rest/routes.js | sort -u > /tmp/route-paths.txt
comm -23 /tmp/doc-paths.txt /tmp/route-paths.txt || true

# 2) Confirm every static chart is emitted
node -e "
import { readFileSync } from 'fs'
import { STATIC_CHART_DEFS } from './shared/metrics.js'
const c = readFileSync('server/services/collector.js','utf8')
const missing = STATIC_CHART_DEFS.filter(d => !c.includes(d.id)).map(d => d.id)
console.log(missing.length ? missing : 'all static charts referenced')
"

# 3) Live smoke (agent running on :18888)
curl -s http://127.0.0.1:18888/api/v1/charts | jq '.charts | keys | length'
curl -s 'http://127.0.0.1:18888/api/v3/data?chart=system.cpu&after=-60&points=30' | jq '.labels,.points'
curl -s 'http://127.0.0.1:18888/api/v3/allmetrics?format=prometheus' | head

---

Part F — Quick status board

Area	Implemented?
All 35 static host metric charts	YES
Per-CPU / disk / net / mount instance charts	YES
Opt-in docker/nginx/redis/postgres/processes/fleet	YES (env-gated)
Swagger core metrics REST (charts/data/allmetrics/contexts v3)	YES
Full swagger operation parity (72 ops)	NO (~38 matched; rest alias/skip/todo)
Cloud / WebRTC / DynCFG	N/A by design

Bottom line: Every host metric chart PearData defines is collected. Every swagger endpoint required to discover and scrape those metrics is implemented on v1/v2/v3 as appropriate. Weights / Metric Correlations and Logs (/api/v*/logs) are done for single-host. Default REST port is 18888. Remaining work is API alias completeness, deeper alert/function semantics, multi-node weight scope, and optional extra collectors — not missing core system metrics.