ADR-0005: Use Beacon API for Telemetry Delivery
Status
Approved
Date
2026-05-27
Context
WatchTower requires reliable frontend telemetry delivery for:
- session summaries
- performance reports
- frontend error diagnostics
- user interaction telemetry
Traditional asynchronous HTTP requests may fail during:
- page unload
- navigation events
- tab closure
- browser backgrounding
This can result in information loss and incomplete observability data.
WatchTower requires a mechanism for reliably transmitting final-session telemetry events without affecting user experience.
Decision
Use the browser-native Beacon API for telemetry delivery and session finalization events.
Rationale
- Beacon API is specifically designed for lightweight asynchronous telemetry delivery
- Allows telemetry transmission during:
- tab close
- page refresh
- route navigation
- browser backgrounding
- Does not block page unload or navigation
- Reduces telemetry loss during session termination
- Lightweight and browser-native
- Best for:
- frontend observability
- analytics
- error reporting
- performance telemetry
Alternatives Considered
Standard Fetch API
Rejected because requests may be cancelled during unload or navigation events.
Fetch API with keepalive
Considered but rejected as the primary mechanism because browser support and reliability is not as reliable as Beacon APIsemantics.
WebSockets
Rejected because bidirectional connections arenot needed for a monitoring app.
Consequences
Positive
- Improved telemetry reliability
- Better session-end diagnostics
- Minimal user experience impact
- Lightweight implementation with no external dependencies
Negative
- Limited payload size
- No response body handling
- Best-effort delivery only
- Not suitable for transactional or critical application operations
Conclusion
The Beacon API was selected because it provides a lightweight and unload-safe mechanism for transmitting critical frontend telemetry data, improving the reliability and completeness of WatchTower observability signals.