This commit is contained in:
ITWorx Pulse release export
@@ -0,0 +1,238 @@
|
||||
# ITWorx Pulse — Product requirements
|
||||
|
||||
## 1. Product statement
|
||||
|
||||
ITWorx Pulse is a self-hosted operational observability platform for a personal/professional Unraid environment. It combines infrastructure, container, storage, network and service health in a configurable dashboard that is easier to understand and operate than a collection of raw monitoring tools.
|
||||
|
||||
Pulse is not a thin Grafana theme. It owns:
|
||||
|
||||
- inventory and relationships;
|
||||
- semantic metrics;
|
||||
- dashboard composition;
|
||||
- status reasoning;
|
||||
- alert lifecycle;
|
||||
- incident grouping;
|
||||
- user experience;
|
||||
- operational documentation and audit.
|
||||
|
||||
Prometheus-compatible systems remain the primary source of time-series history in v1.
|
||||
|
||||
## 2. Primary user
|
||||
|
||||
The primary user is a technically experienced server owner/operator who:
|
||||
|
||||
- manages an Unraid host with many Docker applications;
|
||||
- wants one reliable status surface;
|
||||
- needs detailed drill-down without constant PromQL work;
|
||||
- uses desktop, mobile and a possible wallboard;
|
||||
- values safe automation and read-only monitoring;
|
||||
- may later link incidents to a separate management platform.
|
||||
|
||||
The architecture supports additional viewers/operators but v1 does not need multi-tenant SaaS behavior.
|
||||
|
||||
## 3. Goals
|
||||
|
||||
1. Determine within seconds whether the environment is healthy.
|
||||
2. Explain every degraded/critical/unknown state.
|
||||
3. Allow dashboards to be composed without code.
|
||||
4. Show smooth live behavior and useful history.
|
||||
5. Detect container, storage and service failure independently.
|
||||
6. Prevent alert storms and group related failures.
|
||||
7. Remain safe when telemetry is stale or unavailable.
|
||||
8. Deploy without disrupting existing Unraid services.
|
||||
9. Provide reproducible evidence for operation, backup and recovery.
|
||||
10. Be portfolio-quality in visual, technical and operational terms.
|
||||
|
||||
## 4. Non-goals for v1
|
||||
|
||||
- General log aggregation/search platform.
|
||||
- Kubernetes monitoring.
|
||||
- Multi-organization SaaS.
|
||||
- Automatic remediation.
|
||||
- Container lifecycle management.
|
||||
- Array/storage write operations.
|
||||
- Public unauthenticated monitoring.
|
||||
- AI-required diagnosis.
|
||||
- Unlimited third-party plugin marketplace.
|
||||
- Replacing Prometheus or Grafana without measured need.
|
||||
- Monitoring arbitrary internet targets without an allowlist.
|
||||
|
||||
## 5. Functional capabilities
|
||||
|
||||
### 5.1 Authentication and access
|
||||
|
||||
- Authentik-compatible OIDC login.
|
||||
- Viewer, Operator, Editor and Administrator roles.
|
||||
- Disabled-by-default local break-glass recovery.
|
||||
- Session expiry and logout.
|
||||
- Audit for security/configuration changes.
|
||||
- Wallboard uses a constrained read-only mode or authenticated session.
|
||||
|
||||
### 5.2 Overview
|
||||
|
||||
The default overview shows:
|
||||
|
||||
- global status and explanation;
|
||||
- active incidents/alerts;
|
||||
- uptime, CPU, memory and load;
|
||||
- array and pool status/capacity;
|
||||
- network traffic;
|
||||
- container/application health;
|
||||
- service reachability and latency;
|
||||
- UPS when available;
|
||||
- recent events;
|
||||
- freshness of each source.
|
||||
|
||||
### 5.3 Dashboards
|
||||
|
||||
Users can:
|
||||
|
||||
- create, clone, rename, archive and delete dashboards;
|
||||
- add widgets from a catalog;
|
||||
- drag, resize, lock, duplicate, hide and remove widgets;
|
||||
- configure data, visualization, thresholds and behavior;
|
||||
- preview and edit desktop/tablet/mobile/wallboard layouts;
|
||||
- use variables and cross-filtering;
|
||||
- undo/redo during editing;
|
||||
- save versioned revisions and restore previous versions;
|
||||
- import/export validated JSON;
|
||||
- use system templates;
|
||||
- open widgets fullscreen and drill into entities.
|
||||
|
||||
### 5.4 Inventory and relationships
|
||||
|
||||
Pulse discovers and maintains:
|
||||
|
||||
- host;
|
||||
- hardware and interfaces;
|
||||
- array, pools, disks, filesystems and shares;
|
||||
- containers, images, stacks, volumes and networks;
|
||||
- applications and services;
|
||||
- endpoints and certificates;
|
||||
- data sources, collectors and probes;
|
||||
- dependency relationships.
|
||||
|
||||
Every reconciled field retains source ownership and optional user override.
|
||||
|
||||
### 5.5 Metrics and charts
|
||||
|
||||
- Historical range queries.
|
||||
- Live updates with bounded memory.
|
||||
- Semantic metric catalog.
|
||||
- Units, transformations and aggregation.
|
||||
- Zoom, hover, pause, time range and compare.
|
||||
- Stale/unknown representation.
|
||||
- Query limits and authorization.
|
||||
- CSV/image export where appropriate.
|
||||
- Event annotations.
|
||||
|
||||
### 5.6 Alerts and incidents
|
||||
|
||||
- Versioned alert rules.
|
||||
- Pending, firing, acknowledged and resolved lifecycle.
|
||||
- Unknown, silenced, suppressed and maintenance states.
|
||||
- Hysteresis, cooldown, grouping and dependency suppression.
|
||||
- Notification channels with delivery audit.
|
||||
- Incident creation/grouping from related alerts.
|
||||
- Timeline, notes, ownership and status.
|
||||
- Suggested relationships labeled as uncertain unless proven.
|
||||
|
||||
### 5.7 Operations
|
||||
|
||||
- Datasource health page.
|
||||
- Self-monitoring page.
|
||||
- Backup/restore.
|
||||
- Config export.
|
||||
- Safe deployment and rollback.
|
||||
- Maintenance windows.
|
||||
- Diagnostic bundle with secret redaction.
|
||||
- Clear runbook.
|
||||
|
||||
## 6. Core user journeys
|
||||
|
||||
### Journey A — Morning health check
|
||||
|
||||
1. User opens Pulse.
|
||||
2. Global state loads within the performance budget.
|
||||
3. The page shows Operational or a specific explained deviation.
|
||||
4. User opens an affected component from the status explanation.
|
||||
5. Related graph/event context is visible without constructing a query.
|
||||
|
||||
### Journey B — Customize overview
|
||||
|
||||
1. User enters Edit mode.
|
||||
2. Adds a network chart.
|
||||
3. Resizes and positions it.
|
||||
4. Configures the interface and time range.
|
||||
5. Previews mobile layout.
|
||||
6. Saves.
|
||||
7. Reload preserves all layouts and version history.
|
||||
|
||||
### Journey C — Diagnose service failure
|
||||
|
||||
1. Application container remains running.
|
||||
2. HTTP probe returns failure.
|
||||
3. Service becomes Degraded.
|
||||
4. Alert transitions pending -> firing after its duration.
|
||||
5. Related container/network events appear.
|
||||
6. User acknowledges the incident.
|
||||
7. Recovery resolves the alert and records duration.
|
||||
|
||||
### Journey D — Storage risk
|
||||
|
||||
1. SMART/temperature or pool capacity crosses policy.
|
||||
2. Pulse explains which disk/pool and why.
|
||||
3. User sees current values and history.
|
||||
4. No destructive storage action is offered.
|
||||
5. Optional link opens an external operational workflow later.
|
||||
|
||||
### Journey E — Mobile incident view
|
||||
|
||||
1. User opens Pulse on mobile.
|
||||
2. Active incident is immediately accessible.
|
||||
3. Summary, affected entities, latest values and acknowledgement fit the mobile flow.
|
||||
4. Complex dashboard editing is not required.
|
||||
|
||||
## 7. Status model
|
||||
|
||||
Top-level and entity status:
|
||||
|
||||
- `operational`
|
||||
- `attention`
|
||||
- `degraded`
|
||||
- `critical`
|
||||
- `unknown`
|
||||
- `maintenance`
|
||||
- `disabled`
|
||||
|
||||
Rules:
|
||||
|
||||
- `unknown` outranks a false `operational` claim when required data is stale.
|
||||
- Top-level status includes a list of contributing reasons.
|
||||
- Optional/non-critical component failures do not automatically become critical.
|
||||
- Status aggregation is deterministic and tested.
|
||||
- Color is never the only representation.
|
||||
|
||||
## 8. Acceptance-level non-functional requirements
|
||||
|
||||
- Clean build/deploy from a new checkout.
|
||||
- Responsive at target scale.
|
||||
- At least 17 hours of real wallboard soak without unbounded growth; the
|
||||
product owner explicitly replaced the original 24-hour duration for M10-14
|
||||
on 2026-08-11 while retaining every other performance budget.
|
||||
- Graceful source disconnect/reconnect.
|
||||
- No unrestricted Docker socket in API/web.
|
||||
- Least privilege and non-root runtime.
|
||||
- Automated accessibility checks plus keyboard flows.
|
||||
- Backup/restore and upgrade/rollback.
|
||||
- Secrets absent from repository, logs and evidence.
|
||||
- Traceable requirement-to-test-to-evidence mapping.
|
||||
|
||||
## 9. Success metrics
|
||||
|
||||
- Time to first meaningful overview: under the defined performance budget.
|
||||
- Time to identify a simulated primary fault: less than two minutes in usability validation.
|
||||
- Zero false-green results in stale-source tests.
|
||||
- All baseline failure scenarios detected with expected status and alert behavior.
|
||||
- Dashboard configuration persists and restores across browser/server restart.
|
||||
- Production deployment survives planned restart with healthy state and preserved configuration.
|
||||
Reference in New Issue
Block a user