Publish ITWorx Pulse source

docs/product/MONITORING_REQUIREMENTS.md

@@ -0,0 +1,94 @@
+# Host, container and application monitoring requirements
+
+## Host
+
+Metrics/state:
+- uptime and boot time;
+- CPU total/per core, load, frequency where available;
+- iowait, interrupts and context switches;
+- memory used/available/cache/swap and pressure;
+- filesystem usage/inodes;
+- network per interface, errors/drops;
+- process count and OOM events;
+- temperatures/fans/sensors where supported;
+- GPU usage/memory/temperature where supported;
+- time synchronization health.
+
+Host status must distinguish:
+- high but expected load;
+- sustained saturation;
+- missing collector;
+- stale metrics;
+- thermal risk;
+- resource exhaustion.
+
+## Process explorer
+
+Read-only, bounded view:
+- top CPU;
+- top memory;
+- PID, name, state, runtime;
+- container association when known;
+- process tree on demand.
+
+No process termination. Process command-line arguments, environment and working directory are not shown by default; process rows are bounded and read-only.
+
+## Containers
+
+Inventory:
+- ID/name;
+- image/tag/digest when available;
+- state and health;
+- uptime/start/stop;
+- restart count and exit code;
+- CPU/memory;
+- network;
+- block I/O;
+- ports;
+- volumes/networks;
+- stack/project and labels.
+
+Behavior:
+- preserve runtime state separately from health;
+- expose intentional stop explicitly so a stopped container is not silently treated as healthy;
+- retain source freshness and provenance;
+- expose metric and lifecycle availability explicitly; absent collector fields render as Unknown rather than numeric zero;
+- bound container count and detail collections for predictable response size;
+- detect restart loops over a rolling window;
+- distinguish intentionally stopped/disabled;
+- preserve history across container recreation through stable identity mapping;
+- never infer application health solely from Docker `running`.
+
+### Container identity and recreation
+
+Runtime IDs are source-scoped aliases. A changed runtime ID maps to the same logical container only when the source, compose project and compose service form a unique stable key. Reusing a name without that evidence creates a new logical entity; ambiguous stable keys also refuse to merge. Historical aliases remain visible to reconciliation, and lifecycle events retain the logical entity ID while recording the prior and current runtime IDs.
+## Lifecycle events and instability
+
+Container transitions are normalized into bounded lifecycle events for state, health, restart and intentional-stop changes. Duplicate source/dedup/time events are discarded. A restart loop requires the current container state to be running and at least the configured number of restarts inside the bounded window; a stopped container is not labeled as looping. Ranked resource consumers use deterministic ID/label tie-breaks, and status grids retain text reasons alongside status indicators.
+## Applications
+
+Applications group containers and services into a policy-driven status. Critical component failures degrade the application; critical unknown state remains Unknown. Optional component failures are included in the reasons list and degrade the aggregate without being labeled critical. A service-down state degrades the component even when its container runtime is still running. User overrides for application names and component criticality are applied after discovery and survive repeated discovery projections.
+
+Applications group one or more containers and services.
+
+Fields:
+- friendly name;
+- critical/optional components;
+- dependencies;
+- public/internal URLs;
+- owner/category/tags;
+- aggregate status reasons.
+
+Aggregate status is policy-driven and tested. An optional background worker may fail without making the complete application critical, while a database or main endpoint failure normally degrades it.
+
+## Events
+
+Generate normalized events for:
+- container start/stop/restart/die/health change;
+- image or configuration change;
+- application status change;
+- datasource loss/recovery;
+- host reboot;
+- OOM and thermal events.
+
+Deduplicate noisy repeated events.