ngit-grasp/7d0b-management-dashboard.md

Management Dashboard

ID: 7d0b

⚠️ COORDINATION REQUIRED: This issue is part of the Administrator Observability and Management Strategy (issue ec1f). Before starting work: Check issue ec1f for current phase, dependencies, and coordination requirements. This issue is the primary deliverable for Phase 2 (Insights).

Issue Summary

We need a web-based management dashboard to monitor relay health, view storage and usage statistics, and provide basic operational visibility. This dashboard should display key metrics about relay operations, resource utilization, and usage patterns.

Required Dashboard Features

1. Storage metrics

• Total disk usage (git repos + database)
• Available disk space and percentage used
• Storage breakdown:
  • Git repository data size
  • Database size
  • Temporary/cache size
• Per-user storage usage (top users by storage)
• Per-repository storage usage (largest repos)
• Storage trends over time

2. Usage statistics

• Total number of repositories hosted
• Total number of users (unique npubs)
• Active connections (current WebSocket clients)
• Total events stored
• Events by type (repos, proposals, revisions, etc.)
• Request rate (events/sec, queries/sec)
• Bandwidth usage (inbound/outbound)

3. Performance metrics

• Database query latency (p50, p95, p99)
• Event ingestion rate
• Subscription count (active REQ queries)
• Memory usage
• CPU usage
• Uptime and restart history

4. Recent activity

• Recent repository pushes
• Recent events received
• Recent subscriptions opened
• Recent errors or warnings
• Rate limit hits

5. System health

• Database backend in use (nostrdb/lmdb)
• Configuration summary
• Version information
• Git sync status
• Relay sync status (if applicable)

UI/UX Considerations

• Simple, clean interface (no heavy frontend framework required)
• Real-time updates for live metrics (WebSocket or SSE)
• Responsive design for mobile viewing
• No authentication required for read-only view (or basic auth)
• Separate authenticated view for management actions (see NIP-86 issue)
• Export metrics in machine-readable format (JSON, Prometheus)

Investigation Tasks

Dashboard Implementation

• Research Rust web dashboard frameworks/templates
  • axum + htmx/Alpine.js
  • Tera/Askama templates
  • Server-sent events for live updates
• Design dashboard layout and information hierarchy
• Determine what metrics to expose publicly vs privately
• Decide on authentication strategy (if any for read-only)

Metrics Collection

• Audit what metrics we currently track
• Identify what new metrics need to be collected
• Design metrics storage (in-memory, database, or external)
• Determine update frequency for different metric types
• Research Rust metrics libraries (prometheus, metrics crate)

Storage Calculation

• Implement efficient storage calculation for repos
• Create background task for updating storage metrics
• Design caching strategy to avoid expensive recalculations
• Handle git-specific size considerations (packs, objects)

API Design

• Design JSON API for metrics (for programmatic access)
• Consider Prometheus exporter for monitoring integration
• Plan for metrics retention (historical data)
• Document API endpoints

Performance Impact

• Ensure dashboard doesn't impact relay performance
• Test metrics collection overhead
• Implement rate limiting for dashboard API
• Cache expensive calculations

Questions to Answer

1. What level of detail to show?

   • Individual repository listings vs aggregates?
   • User-level breakdowns vs totals?
   • Historical trends vs current snapshot?

2. How to handle privacy?

   • Show npubs directly or hash them?
   • Public dashboard vs admin-only?
   • What metrics are sensitive?

3. How to update metrics?

   • Real-time vs periodic refresh?
   • Push (SSE/WebSocket) vs pull (polling)?
   • Background calculation vs on-demand?

4. Integration with monitoring?

   • Support Prometheus/Grafana?
   • Custom dashboard only?
   • Both options?

Technology Choices

Consider:

• Backend: Existing axum HTTP server
• Frontend: Server-rendered HTML + minimal JS (htmx or Alpine.js)
• Updates: Server-Sent Events for live metrics
• Styling: Simple CSS or lightweight framework (PicoCSS, Water.css)
• Charts: Chart.js or similar for visualizations

Findings

(To be filled in during investigation)

Implementation Plan

(To be determined after investigation)

Success Criteria

• Dashboard accessible via HTTP endpoint (e.g., /dashboard)
• Clear visibility into storage usage and trends
• Real-time or near-real-time updates for key metrics
• No significant performance impact on relay operations
• Mobile-friendly responsive design
• Basic charts/visualizations for key metrics

Related Issues

• See NIP-86 Relay Management API issue for management actions
• See Storage Limits issue for quota enforcement
• See Database Backend Evaluation for performance metrics