lmxopcua/docs/reqs/StatusDashboardReqs.md

Status Dashboard — Component Requirements

Parent: HLR-009

Reference: LmxProxy Status Dashboard (see dashboard.JPG in project root).

DASH-001: Embedded HTTP Endpoint

The service shall host a lightweight HTTP listener on a configurable port serving a self-contained HTML status dashboard page (no external dependencies).

Acceptance Criteria

• Uses System.Net.HttpListener on a configurable port (Dashboard:Port, default 8081).
• Routes:
  • GET / → HTML dashboard
  • GET /api/status → JSON status report
  • GET /api/health → 200 OK if healthy, 503 if unhealthy
• Only GET requests accepted; other methods return 405.
• Unknown paths return 404.
• All responses include Cache-Control: no-cache, no-store, must-revalidate headers.
• Dashboard can be disabled via config (Dashboard:Enabled, default true).

Details

• HTTP prefix: http://+:{port}/ to bind to all interfaces.
• If HttpListener fails to start (port conflict, missing URL reservation), log Error and continue service startup without the dashboard.
• HTML page is self-contained: inline CSS, no external resources (no CDN, no JavaScript frameworks).

---

DASH-002: Connection Panel

The dashboard shall display a Connection panel showing MXAccess connection state.

Acceptance Criteria

• Shows: Connected (True/False), State (Connected/Disconnected/Reconnecting/Error), Connected Since (UTC timestamp).
• Green left border when Connected, red when Disconnected/Error, yellow when Reconnecting.
• "Connected Since" shows "N/A" when not connected.
• Data sourced from MXAccess client's connection state properties.

Details

• Timestamp format: yyyy-MM-dd HH:mm:ss UTC.
• Panel title: "Connection".

---

DASH-003: Health Panel

The dashboard shall display a Health panel showing overall service health.

Acceptance Criteria

• Three states: Healthy (green text), Degraded (yellow text), Unhealthy (red text).
• Includes a health message string explaining the status.
• Health rules:
  • Not connected to MXAccess → Unhealthy
  • Success rate < 50% with > 100 total operations → Degraded
  • Connected with acceptable success rate → Healthy

Details

• Health message examples: "LmxOpcUa is healthy", "MXAccess client is not connected", "Average success rate is below 50%".
• Green left border for Healthy, yellow for Degraded, red for Unhealthy.

---

DASH-004: Subscriptions Panel

The dashboard shall display a Subscriptions panel showing subscription statistics.

Acceptance Criteria

• Shows: Clients (connected OPC UA client count), Tags (total variable nodes in address space), Active (active MXAccess subscriptions), Delivered (cumulative data change notifications delivered).
• Values update on each dashboard refresh.
• Zero values shown as "0", not blank.

Details

• "Tags" is the count of variable nodes, not object/folder nodes.
• "Active" is the count of distinct MXAccess item subscriptions (after ref-counting — the number of actual AdviseSupervisory calls, not the number of OPC UA monitored items).
• "Delivered" is a running counter since service start (not reset on reconnect).

---

DASH-005: Operations Table

The dashboard shall display an operations metrics table showing performance statistics.

Acceptance Criteria

• Table with columns: Operation, Count, Success Rate, Avg (ms), Min (ms), Max (ms), P95 (ms).
• Rows: Read, Write, Subscribe, Browse.
• Empty cells show em-dash ("—") when no data available (count = 0).
• Success rate displayed as percentage (e.g., "99.8%").
• Latency values rounded to 1 decimal place.

Details

• Metrics sourced from the PerformanceMetrics component (1000-entry rolling buffer for percentile calculation).
• "Browse" row tracks OPC UA browse operations.
• "Subscribe" row tracks OPC UA CreateMonitoredItems operations.

---

DASH-006: Footer

The dashboard shall display a footer with last-updated time and service identification.

Acceptance Criteria

• Format: "Last updated: {timestamp} UTC | Service: ZB.MOM.WW.LmxOpcUa.Host v{version}".
• Timestamp is the server-side UTC time when the HTML was generated.
• Version is read from the assembly version (Assembly.GetExecutingAssembly().GetName().Version).

---

DASH-007: Auto-Refresh

The dashboard page shall auto-refresh to show current status without manual reload.

Acceptance Criteria

• HTML page includes <meta http-equiv="refresh" content="10"> for 10-second auto-refresh.
• No JavaScript required for refresh (pure HTML meta-refresh).
• Refresh interval: configurable via Dashboard:RefreshIntervalSeconds, default 10 seconds.

---

DASH-008: JSON Status API

The /api/status endpoint shall return a JSON object with all dashboard data for programmatic consumption.

Acceptance Criteria

• Response Content-Type: application/json.
• JSON structure includes: connection state, health status, subscription statistics, and operation metrics.
• Same data as the HTML dashboard, structured for machine consumption.
• Suitable for integration with external monitoring tools.

---

DASH-009: Galaxy Info Panel

The dashboard shall display a Galaxy Info panel showing Galaxy Repository state.

Acceptance Criteria

• Shows: Galaxy Name (e.g., ZB), DB Status (Connected/Disconnected), Last Deploy (timestamp from galaxy.time_of_last_deploy), Objects (count), Attributes (count), Last Rebuild (timestamp of last address space rebuild).
• Provides visibility into the Galaxy Repository component's state independently of MXAccess connection status.

Details

• "DB Status" reflects whether the most recent change detection poll succeeded.
• "Last Deploy" shows the raw time_of_last_deploy value from the Galaxy database.
• "Objects" and "Attributes" show counts from the most recent successful hierarchy/attribute query.