peardata/docs/EXTENDING.md

Extending PearData

Add a chart / context

1. Define the chart in shared/metrics.js (STATIC_CHART_DEFS, or registerChart() for instances).
2. Emit samples from server/services/collector.js (or a new collector module).
3. Store + REST/RPC pick it up automatically via getAllChartDefs() / CHART_BY_ID.
4. Ensure the chart lands in the Charts wall TOC via shared/taxonomy.js (sectionForChart matchers). Prefer a real section over Other.
5. Document dimensions in DATA-MODEL.md.
6. The desktop Charts tab picks it up automatically (no per-chart HTML). Overview spotlight is optional.

Coverage is asserted by test/taxonomy-coverage.test.js.

Add an RPC method

shared/protocol.js

export const MethodRoles = Object.freeze({
  // ...
  listContainers: Roles.viewer,
  restartCollector: Roles.admin,
})

shared/schema.js

Validate args.

server/services/… + server/handlers/monitor.js

Register with session.respond(...). Use { hot: true } for high-frequency paths.

Client

await manager.request(Methods.listContainers, {})

Docs + tests

Update PROTOCOL.md and add a brittle test.

Add a REST route

Edit server/rest/routes.js — keep stable /api/v3/... path naming.

Add a job

Register in server/services/jobs.js JOB_HANDLERS.

retrainAnomaly: async (args) => getAnomalyEngine().retrain(getStore(), args)

Operators run via runJob (retrainAnomaly is registered).

Add a collector plugin (pattern)

server/services/collectors/
  docker.js      # PEARDATA_DOCKER=1 — cgroup + Docker socket names (installer auto-enables)
  peardock.js    # bridge (planned)

Have pipeline.js start each enabled collector; all emit samples batches into the same store.

Docker collector (shipped spike)

1. Set PEARDATA_DOCKER=1 on the agent (or re-run the installer when Docker is present).
2. Ensure peardata can read the socket (usermod -aG docker peardata + unit SupplementaryGroups=… docker).
3. Charts: docker.containers, docker.cpu.<shortId>, docker.mem.<shortId> (stable ids); titles/families use human names (dozzle · CPU).
4. Discovery: cgroup v2 docker-*.scope / libpod-*.scope; names via loadContainerNameMap (unix HTTP API → docker ps → filesystem) + Compose labels (shared/container-names.js).
5. Cgroups collector reuses the same name map so cgroup.* cards are not bare hashes.
6. UI: user-guide/containers.md.

Process top-N collector

1. Default on for Linux (PEARDATA_PROCESSES=0 to disable charts). Optional PEARDATA_PROCESSES_TOP=8.
2. Charts: processes.top_cpu / top_rss / top_io / top_threads (dimensions = process comm names).
3. Desktop Processes tab + RPC listProcesses / GET /api/v3/processes — per-PID live table (not just top-N charts).
4. Linux /proc only; safe no-op on other platforms.

Nginx stub_status plugin

1. Set PEARDATA_NGINX=1 and PEARDATA_NGINX_URL=….
2. Charts: nginx.connections, nginx.requests.
3. Base class: server/services/collectors/plugin.js (CollectorPlugin).

Redis INFO plugin

1. Set PEARDATA_REDIS=1 and optional PEARDATA_REDIS_URL.
2. Charts: redis.memory, redis.clients, redis.stats.

Postgres plugin

1. Set PEARDATA_POSTGRES=1 (+ host/port).
2. Charts: postgres.up (TCP probe); optional postgres.stats via PEARDATA_POSTGRES_STATS_URL.

Export / Prometheus push

• Job exportSnapshot / RPC exportSnapshot / REST GET /api/v3/export
• Job prometheusPush → PEARDATA_PUSHGATEWAY_URL
• Optional file write: PEARDATA_EXPORT_DIR

Webhook notifications

1. Set PEARDATA_WEBHOOK_URL=https://… and optional PEARDATA_WEBHOOK_SECRET.
2. When a secret is set, requests include:
   • X-PearData-Timestamp
   • X-PearData-Signature: sha256=<HMAC-SHA256(secret, ${ts}.${body})>
3. Verify with verifyWebhookSignature from server/services/notify.js.
4. Desktop: toggle “Desktop notifications” in the Anomalies panel.

z-score / retrain

1. PEARDATA_ANOMALY_MODE=zscore|hybrid for rolling z-score fires.
2. Job retrainAnomaly (operator) refits warn/crit from store history (mean ± z·stdev).
3. Helpers live in server/services/zscore.js.

REST HyperDHT tunnel (holesail-style)

1. PEARDATA_REST_TUNNEL=1 (+ optional PEARDATA_REST_TUNNEL_SEED).
2. Agent announces a HyperDHT key that proxies TCP → local REST.
3. Inspect: GET /api/v3/tunnel or getServerInfo.restTunnel.

PearDock bridge

1. Set PEARDATA_PEARDOCK=1 and PEARDATA_PEARDOCK_PEERS=<dockOrAgentPk>,….
2. Bridge dials peers, reads getAllMetrics, remaps docker.* → peardock.*.
3. Prefer public APIs / your own modules when integrating with PearDock (both are AGPL-3).

Parent peer (fleet aggregator)

Shipped opt-in spike:

1. Set PEARDATA_PARENT=1 and PEARDATA_PARENT_PEERS=<childPk>,….
2. Parent dials children over HyperDHT (PearDataConnection), polls health + metrics.
3. Emits fleet.cpu, fleet.ram, fleet.children into the local store.
4. REST: GET /api/v3/nodes (multi), /api/v3/fleet, /api/v3/stream_path.
5. RPC: getFleetHealth, listChildPeers.

PearDock / PearVirt hooks

• Prefer RPC adapters over scraping: call dock/virt methods, map to PearData contexts.
• PearData is AGPL-3.0-only — see LICENSE. Depend on public APIs when integrating sibling projects.

Desktop chrome

Keep <pear-ctrl>, titlebar drag regions, and pear.gui.resizable. See DESKTOP.md.

Rebrand (fork)

npm run rename -- my-monitor MyMonitor

Review invite prefix / env prefix, then npm test.