jedarden/zai-proxy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(dashboard): enhance API reference with SSE implementation details and storage backend specs

Browse source 
- 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 <noreply@anthropic.com>
Bead-Id: bf-4rx
This commit is contained in:
jedarden 2026-06-21 10:30:19 -04:00
parent 8dcadbb051
commit c3289efcf9
1 changed files with 33 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
docs/notes/DASHBOARD_API_REFERENCE.md
View file

@ -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.
---