From c3289efcf920d0cd89ba96bdf5bbdd823e418baa Mon Sep 17 00:00:00 2001 From: jedarden Date: Sun, 21 Jun 2026 10:30:19 -0400 Subject: [PATCH] docs(dashboard): enhance API reference with SSE implementation details and storage backend specs - Add detailed SSE connection behavior and slow client detection - Add server-side implementation details (broadcast hub, client management) - Add automatic operations section (downsampling, cleanup, WAL mode) - Add storage backend details (database, write strategy, query strategy) - Fix retention period for metrics_5s (24h, not 6h) Co-Authored-By: Claude Bead-Id: bf-4rx --- docs/notes/DASHBOARD_API_REFERENCE.md | 36 ++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/notes/DASHBOARD_API_REFERENCE.md b/docs/notes/DASHBOARD_API_REFERENCE.md index fcd1f03..b2329dd 100644 --- a/docs/notes/DASHBOARD_API_REFERENCE.md +++ b/docs/notes/DASHBOARD_API_REFERENCE.md @@ -437,8 +437,20 @@ This is an SSE comment (prefixed with `:`) and should be ignored by clients but - **Persistent Connection:** The connection remains open until the client disconnects or the server terminates. - **Automatic Reconnect:** Clients should implement reconnection logic with exponential backoff. -- **Buffer Overflow:** Slow clients may be disconnected if their send buffer fills up (16-message buffer per client). -- **Broadcast:** All connected clients receive the same metric updates simultaneously. +- **Slow Client Detection:** Clients with full send buffers are automatically disconnected to prevent backpressure buildup. +- **Broadcast Capacity:** 100-message buffer for the broadcast channel. +- **Concurrent Clients:** No hard limit (limited by system resources). +- **HTTP/2 Compatible:** Works with HTTP/2 and cloudflared tunnels (uses standard HTTP GET, not WebSocket upgrade). + +#### Server-Side Implementation + +The SSE endpoint is implemented via a broadcast hub (`/dashboard/api/sse.go`): + +- **Broadcast Channel:** Buffered channel (capacity: 100) for metric snapshots +- **Client Registration:** Concurrent-safe client registration/unregistration +- **Slow Client Protection:** Clients with full send buffers are automatically disconnected +- **Heartbeat:** Sent every 30 seconds to keep connections alive +- **Client Context:** Disconnections detected via `r.Context().Done()` #### Example Clients @@ -508,9 +520,27 @@ The dashboard stores metrics at two granularities with different retention polic | Table | Granularity | Retention | Purpose | |-------|-------------|-----------|---------| -| `metrics_5s` | 5 seconds | 6 hours | High-resolution recent data | +| `metrics_5s` | 5 seconds | 24 hours | High-resolution recent data | | `metrics_1m` | 1 minute | 7 days | Downsampled historical data | +### Automatic Operations + +- **Downsampling:** Runs every 10 minutes, aggregates 5-second data into 1-minute averages +- **Cleanup:** Runs every hour, deletes data beyond retention windows +- **WAL Mode:** Enabled for performance and concurrency + +### Storage Backend + +**Database:** SQLite with WAL mode + +**Path:** Configured via `DB_PATH` environment variable (default: `/data/dashboard.db`) + +**Write Strategy:** Asynchronous writes via buffered channel (capacity: 1000) + +**Query Strategy:** Time-based table selection +- Queries > 1 hour use `metrics_1m` (downsampled) +- Queries ≤ 1 hour use `metrics_5s` (high-resolution) + Data is automatically downsampled from 5-second to 1-minute granularity every 10 minutes. Old data beyond retention periods is automatically cleaned up. ---