flvx/docs/superpowers/specs/2026-04-28-monitoring-retention-storage-design.md

Monitoring Retention And Storage Display Design

Goal

Add an administrator-facing configuration for monitoring data retention and display the current database storage usage in the configuration page.

Scope

• Add a single config key: monitor_retention_days.
• Default retention is 7 days.
• Apply the retention window uniformly to:
  • node_metric
  • tunnel_metric
  • service_monitor_result
  • tunnel_quality
• Show database usage on the config page as a read-only operational value.

Non-Goals

• No per-table retention settings.
• No manual purge button.
• No database vacuum/compaction action.
• No frontend test framework changes.

Backend Design

Retention Config

• Store monitor_retention_days in vite_config, consistent with existing site settings.
• Accept integer values from 1 through 3650.
• Missing or invalid stored values fall back to 7 days.
• normalizeAndValidateConfigValue rejects invalid user-submitted values so bad config does not get saved through the API.

Cleanup Flow

• metrics.IngestionService.pruneMetrics() reads monitor_retention_days from the repository each hourly cleanup cycle.
• The computed cutoff is used for node_metric, tunnel_metric, and service_monitor_result.
• tunnel_quality uses the same retention config.
• tunnel_quality cleanup must run even when real-time tunnel quality probing is disabled; disabling probing should stop new probe writes, not stop cleanup.

Database Storage API

• Add an admin-only API endpoint for storage summary, for example /api/v1/system/storage.
• Response fields:
  • dbType: sqlite or postgres
  • databaseSizeBytes: raw byte count
  • databaseSizeText: human-readable formatted size
• SQLite implementation reports the DB file size and includes -wal and -shm sidecar files when present.
• PostgreSQL implementation uses pg_database_size(current_database()).
• If size cannot be determined, return an API error rather than a misleading zero.

Frontend Design

• Add monitor_retention_days to the config page.
• Label: 监控数据保留天数.
• Description: 统一清理节点指标、隧道流量、服务监控结果和隧道质量历史；默认 7 天。
• Use a regular numeric input through the existing config rendering path.
• Fetch database storage summary when the config page loads.
• Display a read-only card/row named 数据库占用 with databaseSizeText.
• If fetching fails, show 获取失败 and keep config editing usable.

Error Handling

• Invalid retention values return a validation error on save.
• Cleanup logs individual prune failures and continues with other tables, matching existing monitoring cleanup behavior.
• Storage summary failures are non-blocking in the frontend.

Testing

• Backend unit tests for retention config parsing and validation.
• Backend tests proving custom retention is used by monitoring cleanup.
• Backend API/repository test for SQLite storage size returning a non-negative byte count and formatted text.
• Run go test ./... in go-backend.
• Run pnpm run build in vite-frontend.