feat(telemetry): add portable local telemetry plane

2026-07-28 00:54:11 +03:00
parent 9fc002d86f
commit b8a008b50e
16 changed files with 1486 additions and 0 deletions
@@ -0,0 +1,81 @@
+# NDC Mission Core local telemetry plane
+
+Portable local-only telemetry infrastructure for compute contours.
+
+One Docker Compose project, `ndc-mission-core-telemetry`, owns three isolated
+containers:
+
+- `ndc-mission-core-mqtt-broker` — Eclipse Mosquitto `2.1.2-alpine`;
+- `ndc-mission-core-telemetry-timescaledb` — TimescaleDB HA OSS
+  `pg16.14-ts2.28.2-all-oss`;
+- `ndc-mission-core-telemetry-normalizer` — Mission Core telemetry normalizer.
+
+The Telegraf configuration templates cover Windows and Linux, but the agent runs as a
+host service rather than inside this Compose project. This preserves access to native
+Windows performance counters, Docker Desktop and NVIDIA telemetry.
+
+The normalizer exposes a read-only normalized telemetry adapter on
+`127.0.0.1:18030`. Mission Core reads this adapter; the browser never receives MQTT or
+Timescale credentials, and Timescale is not published on a host port.
+
+The stack is one deployment contour, not one multi-process container. Keeping broker,
+normalizer and database in separate containers preserves independent health checks,
+least-privilege boundaries and rollback while Compose provides one operator lifecycle:
+
+```bash
+docker compose ps
+docker compose up -d
+docker compose down
+```
+
+All NODE.DC-owned Docker objects use the lowercase `ndc-` namespace. Docker names are
+case-sensitive identifiers, so the product prefix is normalized to lowercase while the
+product name remains NODE.DC in operator-facing copy.
+
+This directory does not contain credentials. Copy `.env.example` to `.env`, generate
+unique passwords and build the ACL/password files before starting the stack.
+
+```bash
+uv run python prepare.py --initialize --mqtt-bind-address <MISSION_CORE_HOST_LAN_IP>
+docker compose up -d --build
+```
+
+Expected Docker object names:
+
+```text
+project:   ndc-mission-core-telemetry
+network:   ndc-mission-core-telemetry
+containers:
+  ndc-mission-core-mqtt-broker
+  ndc-mission-core-telemetry-normalizer
+  ndc-mission-core-telemetry-timescaledb
+volumes:
+  ndc-mission-core-mqtt-data
+  ndc-mission-core-telemetry-timescale-data
+```
+
+`prepare.py` passes passwords to `mosquitto_passwd` through stdin. Secrets are not placed
+in process arguments or committed files. `--initialize` generates `.env` with mode
+`0600` and refuses to replace existing credentials. The generated `.env` and `runtime/`
+directory are ignored by Git.
+
+The product architecture and topic contract are defined in
+`docs/adr/0031-local-compute-contour-telemetry-plane.md`.
+
+## Worker agent
+
+Worker 006 uses the official Windows Telegraf distribution as the host service
+`NDC Mission Core Telemetry Agent`. Install or update it with:
+
+```powershell
+.\telegraf\Install-NdcMissionCoreTelegraf.ps1
+.\telegraf\Update-NdcMissionCoreTelegraf.ps1
+```
+
+The update path validates the candidate configuration, backs up the active
+configuration and rolls back if the service does not return to `Running`. MQTT
+credentials are scoped to the service environment and must not be passed on a command
+line or stored in the repository.
+
+The stack and agent are intentionally not started by repository tests. Provisioning a
+machine is a separate, explicit operation.