Files
Sable/docs/SENTRY_INTEGRATION.md
hazre 45c359dea6 refactor(ci): unify cloudflare infra workflows and remove is_release_tag
Signed-off-by: hazre <[email protected]>

fix: resolve rebase merge conflicts

Signed-off-by: hazre <[email protected]>
2026-07-26 13:33:40 -05:00

502 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Sentry Integration for Sable
This document describes the Sentry error tracking and monitoring integration added to Sable.
For a detailed breakdown of what data is collected and how it is protected, see [SENTRY_PRIVACY.md](./SENTRY_PRIVACY.md).
## Overview
Sentry is integrated with Sable to provide:
- **Error tracking**: Automatic capture and reporting of errors and exceptions
- **Performance monitoring**: Track application performance and identify bottlenecks
- **User feedback**: Collect bug reports with context from users
- **Session replay**: Record user sessions (with privacy controls) for debugging
- **Breadcrumbs**: Track user actions leading up to errors
- **Debug log integration**: Attach internal debug logs to error reports
## Bug Fixes (found via Sentry Replay)
Two non-Sentry bugs were found and fixed in the course of building this integration:
### Scroll-to-bottom after list→subscription timeline expansion
**Problem**: When a room with a single cached event (list subscription, `timeline_limit=1`) becomes
fully subscribed and the SDK delivers N new events, the `TimelineReset` fires before any events land
on the fresh timeline. The "stay at bottom" effect queues a `scrollToBottom` while the DOM is still
empty (range `end=0`). By the time real events load, the scroll has already fired against an empty
container and is a no-op — the user's view stalls mid-list.
**Fix**: The stay-at-bottom `useEffect` now increments `scrollToBottomRef.current.count` after
calling `setTimeline(getInitialTimeline(room))`, re-queuing the scroll for after the first batch of
events arrives and the DOM has content.
**File**: `src/app/features/room/RoomTimeline.tsx`
### TS2367 redundant phase guard in `useCallSignaling`
**Problem**: A `phase !== undefined` guard was always evaluating to `true` because the TypeScript
type for `phase` had no `undefined` branch at that point in the control flow.
**Fix**: Removed the dead branch. TypeScript no longer emits a TS2367 comparison error here.
**File**: `src/app/hooks/useCallSignaling.ts`
---
## Features
### 1. Automatic Error Tracking
All errors are automatically captured and sent to Sentry with:
- Stack traces
- User context (anonymized)
- Device and browser information
- Recent breadcrumbs (user actions)
- Debug logs (when enabled)
### 2. Debug Logger Integration
The internal debug logger now integrates with Sentry:
- **Breadcrumbs**: All debug logs are added as breadcrumbs for context
- **Error capture**: Errors logged to the debug logger are automatically sent to Sentry
- **Warning sampling**: 10% of warnings are sent to Sentry to avoid overwhelming the system
- **Log attachment**: Recent logs can be attached to bug reports for additional context
Key integration points:
- `src/app/utils/debugLogger.ts` - Enhanced with Sentry breadcrumb and error capture
- Automatic breadcrumb creation for all log entries
- Error objects in log data are captured as exceptions
- 10% sampling rate for warnings to control volume
### 3. Bug Report Modal Integration
The bug report modal (`/bugreport` command or "Bug Report" button) now includes:
- **Optional Sentry reporting**: Checkbox to send anonymous reports to Sentry
- **Debug log attachment**: Option to include recent debug logs (last 100 entries)
- **User feedback API**: Bug reports are sent as Sentry user feedback for better visibility
- **Privacy controls**: Users can opt-in to Sentry reporting
Integration points:
- `src/app/features/bug-report/BugReportModal.tsx` - Added Sentry options and submission logic
- Automatically attaches platform info, version, and user agent
- Links bug reports to Sentry events for tracking
### 4. Privacy & Security
Comprehensive data scrubbing (full details in [SENTRY_PRIVACY.md](./SENTRY_PRIVACY.md)):
- **Token masking**: All access tokens, passwords, and authentication data are redacted
- **Matrix ID anonymization**: User IDs, room IDs, and event IDs are masked
- **Session replay privacy**: All text, media, and form inputs are masked when replay is enabled
- **request header sanitization**: Authorization headers are removed
- **User opt-in**: Users can enable Sentry via settings
Sensitive patterns automatically redacted:
- `access_token`, `password`, `token`, `refresh_token`
- `session_id`, `sync_token`, `next_batch`
- Matrix user IDs (`@user:server`)
- Matrix room IDs (`!room:server`)
- Matrix event IDs (`$event_id`)
### 5. Settings UI
Sentry controls are split across two settings locations:
**Settings → General → Diagnostics & Privacy** (user-facing):
- **Enable/disable error reporting**: Toggle Sentry error tracking on/off
- **Session replay control**: Enable/disable session recording (opt-in)
- Link to the privacy policy
**Settings → Developer Tools → Error Tracking (Sentry)** (power-user):
- **Breadcrumb categories**: Granular control over which log categories are sent as breadcrumbs
- **Session stats**: Live error/warning counts for the current page load
- **Export debug logs**: Download the in-memory log buffer as JSON for offline analysis
- **Attach debug logs**: Manually attach recent logs to next error report
- **Test buttons**: Force an error, test feedback, test message capture
### 6. First-Login Consent Banner
When `VITE_SENTRY_DSN` is set and a user has never seen the crash-reporting notice (i.e. `sable_sentry_enabled` is absent from `localStorage`), a dismissible banner slides in from the bottom of the screen on first load. It explains that anonymous crash reporting is available and asks if the user wants to enable it.
**Actions available in the banner:**
| Button | Effect |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Enable** | Sets `sable_sentry_enabled = true` in `localStorage` and reloads the page so Sentry initialises. Reporting begins after reload. |
| **No thanks** / × (close) | Sets `sable_sentry_enabled = false` in `localStorage` and dismisses the banner with a fade-out animation. Sentry stays disabled. |
Once the user has interacted with the banner (either action), it never appears again. The same preference can be changed later in **Settings → General → Diagnostics & Privacy**.
**Implementation:** `src/app/components/telemetry-consent/TelemetryConsentBanner.tsx` — rendered inside the logged-in client layout so it only appears after a session is established.
> **Self-hosters**: If you do not set `VITE_SENTRY_DSN`, the banner is never shown and Sentry is entirely disabled at build time. No network requests are made to Sentry.
## Configuration
### Environment Variables
Configure Sentry via environment variables:
```env
# Required: Your Sentry DSN (if not set, Sentry is disabled)
VITE_SENTRY_DSN=https://[email protected]/project-id
# Required: Environment name - controls sampling rates
# - "production" = 10% trace/replay sampling (cost-effective for production)
# - "preview" = 100% trace/replay sampling (full debugging for PR previews)
# - "development" = 100% trace/replay sampling (full debugging for local dev)
VITE_SENTRY_ENVIRONMENT=production
# Optional: Release version for tracking (defaults to VITE_APP_VERSION)
VITE_SENTRY_RELEASE=1.7.0
# Optional: For uploading source maps to Sentry (CI/CD only)
SENTRY_AUTH_TOKEN=your-sentry-auth-token
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug
```
### Self-Hosting with Docker
Sable is compiled at build time, so `VITE_*` variables must be passed as Docker
**build arguments** — they cannot be injected at container runtime via a plain
`docker run -e` flag. The easiest way for self-hosters to supply them is with
a `.env` file and `docker-compose`.
#### 1. Create a `.env` file
```env
# .env — never commit this file
VITE_SENTRY_DSN=https://[email protected]/XXXXXXX
VITE_SENTRY_ENVIRONMENT=production
```
The `VITE_SENTRY_ENVIRONMENT` value controls sampling rates (see table below).
Leave it as `production` for a live deployment.
#### 2. Reference it in `docker-compose.yml`
The `args` block forwards the variables from `.env` into the Docker build
stage so Vite can embed them in the bundle:
```yaml
services:
sable:
build:
context: .
args:
- VITE_SENTRY_DSN=${VITE_SENTRY_DSN}
- VITE_SENTRY_ENVIRONMENT=${VITE_SENTRY_ENVIRONMENT}
ports:
- '8080:8080'
```
Then build and start with:
```bash
docker compose --env-file .env up --build
```
#### 3. Verify it worked
Open the browser console after loading your instance — you should see:
```
[Sentry] Initialized for production environment
[Sentry] DSN configured: https://your-key@o...
```
If you see `[Sentry] Disabled - no DSN provided`, the build arg was not
picked up — double-check the `args` block and that your `.env` file is in the
same directory as `docker-compose.yml`.
#### Building without Compose
If you use plain `docker build`, pass build args directly:
```bash
docker build \
--build-arg VITE_SENTRY_DSN="https://[email protected]/XXXXXXX" \
--build-arg VITE_SENTRY_ENVIRONMENT="production" \
-t sable .
```
> **Security note:** DSN values embedded in the JavaScript bundle are visible
> to any user who opens DevTools. This is normal and expected for Sentry DSNs —
> they are designed to be public-facing ingest keys. Rate-limiting and origin
> restrictions on the Sentry project side are the correct controls.
### Deployment Configuration
**Production deployment (from `dev` branch):**
- Set `VITE_SENTRY_ENVIRONMENT=production`
- Gets 10% sampling for traces and session replay
- Cost-effective for production usage
- Configured in `.github/workflows/cloudflare-web.yml`
**Preview deployments (PR previews, Cloudflare Pages):**
- Set `VITE_SENTRY_ENVIRONMENT=preview`
- Gets 100% sampling for traces and session replay
- Full debugging capabilities for testing
- Configured in `.github/workflows/cloudflare-web-preview.yml`
**Desktop & mobile (Tauri) builds (`.github/workflows/tauri-build.yml`):**
- Tagged releases (`v*`) → `VITE_SENTRY_ENVIRONMENT=production` (10% sampling)
- Nightly builds (from `dev`) → `VITE_SENTRY_ENVIRONMENT=preview` (100% sampling)
- `VITE_SENTRY_DSN`, `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` are injected from repository secrets into the `build`, `android`, and `ios` jobs
- Source maps are generated for release builds **only** when the Sentry upload credentials are present, then uploaded and deleted from the bundle via `filesToDeleteAfterUpload` — so no `.map` files ship inside the app bundle. Without credentials, no source maps are emitted
- The `release` is `VITE_APP_VERSION` (the tag version, or the nightly version), matching the release the source maps are uploaded against so Sentry can un-minify stack traces
- Native (Rust) panics are captured via the `sentry` crate, consent-gated to match the JS opt-in: the SDK initialises at startup but a `before_send` hook drops all events until the frontend calls `set_native_sentry_enabled(true)` after its `sable_sentry_enabled` check
**Local development:**
- `VITE_SENTRY_ENVIRONMENT` not set (defaults to `development` via Vite MODE)
- Gets 100% sampling for traces and session replay
- Full debugging capabilities
**Sampling rates by environment:**
```
Environment | Traces | Profiles | Session Replay | Error Replay
---------------|--------|----------|----------------|-------------
production | 10% | 10% | 10% | 100%
preview | 100% | 100% | 100% | 100%
development | 100% | 100% | 100% | 100%
```
> **Browser profiling requires a `Document-Policy: js-profiling` response header** on your HTML document.
> This is already included in the provided `Caddyfile` and nginx config. For other servers, add the header to
> the response serving `index.html`.
### User Preferences
Users can control Sentry via localStorage:
```javascript
// Disable Sentry entirely (requires page refresh)
localStorage.setItem('sable_sentry_enabled', 'false');
// Disable session replay only (requires page refresh)
localStorage.setItem('sable_sentry_replay_enabled', 'false');
```
Or use the UI in Settings → General → Diagnostics & Privacy.
## Custom Instrumentation
Beyond automatic error capture, Sable has hand-crafted monitoring at key
lifecycle points. See [SENTRY_PRIVACY.md](./SENTRY_PRIVACY.md) for the full
metrics reference. Key areas:
| Area | What's tracked |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Auth** | Login failures (by `errcode`), forced server logouts |
| **Sync** | Transport type, degraded states, cycle stats, initial sync latency, time-to-ready, total rooms loaded, active subscriptions |
| **Cryptography** | Decryption failures (by failure reason), key backup errors, store wipes, E2E verification outcomes, bulk decryption latency |
| **Messaging** | Send latency, send errors, local-echo `NOT_SENT` events |
| **Timeline** | Opens, virtual window size, jump-load latency, re-initialisations, `limited` sync resets, scroll offset at load, pagination errors |
| **Pagination** | Pagination latency (`sable.pagination.latency_ms`) and errors per direction |
| **Sliding sync** | Room subscription latency (`sable.sync.room_sub_latency_ms`), events per subscription batch (`sable.sync.room_sub_event_count`) |
| **Scroll / UX** | `atBottom` transitions with rapid-flip anomaly detection, scroll-to-bottom trigger warnings when user is scrolled up |
| **Calls** | `sable.call.start.attempt/error`, `sable.call.answered`, `sable.call.declined`, active/ended/timeout counters |
| **Message actions** | `sable.message.delete.*`, `sable.message.forward.*`, `sable.message.report.*`, `sable.message.reaction.toggle` |
| **Media** | Upload latency, upload size, cache stats |
| **Background clients** | Per-account notification client count, startup failures |
Fatal errors that are caught by `useAsyncCallback` state (and therefore never
reach React's ErrorBoundary) are explicitly forwarded with `captureException`:
- Client load failure (`phase: load`)
- Client start failure (`phase: start`)
- Background notification client startup failure
### Breadcrumb categories
All hand-crafted breadcrumbs use structured Sentry categories that appear in
the Sentry issue timeline and can be filtered in the developer settings panel.
| Category | Where emitted | What it records |
| ----------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
| `auth` | `ClientRoot.tsx` | Login session start, forced logout |
| `sync` | `initMatrix.ts`, `SyncStatus.tsx` | Sync state transitions, degraded states, client ready |
| `sync.sliding` | `slidingSync.ts` | First room subscription data: latency, event count |
| `timeline.sync` | `RoomTimeline.tsx` | SDK-initiated `TimelineReset` (limited sync gap) — fires before events arrive |
| `timeline.events` | `RoomTimeline.tsx` | Every `eventsLength` batch: delta, batch size label, range gap, `atBottom` |
| `ui.scroll` | `RoomTimeline.tsx` | `atBottom` true→false transitions, rapid-flip warnings, scroll-to-bottom fires |
| `ui.timeline` | `RoomTimeline.tsx` | Virtual paginator window shifts (range start/end changes) |
| `call.signal` | `useCallSignaling.ts`, `IncomingCallModal.tsx` | Call signal state changes, answer/decline |
| `crypto` | `useKeyBackup.ts` | Key backup errors |
| `media` | `ClientNonUIFeatures.tsx` | Blob cache stats on blob URL creation |
## Implementation Details
### Files Modified
1. **`src/instrument.ts`**
- Enhanced Sentry initialization with privacy controls
- Added user preference checks
- Improved data scrubbing for Matrix-specific data
- Conditional session replay based on user settings
2. **`src/app/utils/debugLogger.ts`**
- Added Sentry import
- New `sendToSentry()` method for breadcrumbs and error capture
- New `exportLogsForSentry()` method
- New `attachLogsToSentry()` method
- Integrated into main `log()` method
3. **`src/app/features/bug-report/BugReportModal.tsx`**
- Added Sentry and debug logger imports
- New state for Sentry options (`sendToSentry`, `includeDebugLogs`)
- Enhanced `handleSubmit()` with Sentry user feedback
- New UI checkboxes for Sentry options
4. **`src/app/features/settings/developer-tools/SentrySettings.tsx`** _(new file)_
- New settings panel component
- Controls for Sentry and session replay
- Manual log attachment
5. **`src/app/features/settings/developer-tools/DevelopTools.tsx`**
- Added SentrySettings import and component
### Sentry Configuration
- **Tracing sample rate**: 100% in development, 10% in production
- **Session replay sample rate**: 10% of all sessions, 100% of error sessions
- **Warning capture rate**: 10% to avoid overwhelming Sentry
- **Breadcrumb retention**: All breadcrumbs retained for context
- **Log attachment limit**: Last 100 debug log entries
### Performance Considerations
- Breadcrumbs are added synchronously but are low-overhead
- Error capture is asynchronous and non-blocking
- Warning sampling (10%) prevents excessive Sentry usage
- Session replay only captures when enabled by user
- Debug log attachment limited to most recent entries
## Usage Examples
### For Developers
```typescript
import { getDebugLogger } from '$utils/debugLogger';
// Errors are automatically sent to Sentry
const logger = createDebugLogger('myNamespace');
logger.error('sync', 'Sync failed', error); // Sent to Sentry
// Manually attach logs before capturing an error
const debugLogger = getDebugLogger();
debugLogger.attachLogsToSentry(100);
Sentry.captureException(error);
```
### For Users
1. **Report a bug with Sentry**:
- Type `/bugreport` or click "Bug Report" button
- Fill in the form
- Check "Send anonymous report to Sentry"
- Check "Include recent debug logs" for more context
- Submit
2. **Disable Sentry**:
- Go to Settings → Developer Tools
- Enable Developer Tools
- Scroll to "Error Tracking (Sentry)"
- Toggle off "Enable Sentry Error Tracking"
- Refresh the page
## Benefits
### For Users
- Better bug tracking and faster fixes
- Optional participation with privacy controls
- Transparent data usage
### For Developers
- Real-time error notifications
- Rich context with breadcrumbs and logs
- Performance monitoring
- User feedback integrated with errors
- Replay sessions to reproduce bugs
## Privacy Commitment
See [SENTRY_PRIVACY.md](./SENTRY_PRIVACY.md) for a complete, code-linked breakdown of what is collected, what is masked, and how user controls work.
In summary, all data sent to Sentry is:
- **Off by default**: Sentry is disabled until the user explicitly opts in
- **Anonymized**: No personal data or message content
- **Filtered**: Tokens, passwords, and IDs are redacted
- **Minimal**: Only error context and debug info
- **Transparent**: Users can see what's being sent
No message content, room conversations, or personal information is ever sent to Sentry.
## Testing
To test the integration:
1. **Test error reporting**:
- Go to Settings → General → Diagnostics & Privacy
- Check that Sentry is enabled and `VITE_SENTRY_DSN` is set
- Open the browser console and run: `window.Sentry?.captureMessage('Test message')`
- Check the Sentry dashboard for the event
2. **Test bug report integration**:
- Type `/bugreport`
- Fill in form with test data
- Enable "Send anonymous report to Sentry"
- Submit and check Sentry
3. **Test privacy controls**:
- Disable Sentry in settings
- Refresh page
- Trigger an error (should not appear in Sentry)
- Re-enable and verify errors are captured again
## Troubleshooting
### Sentry not capturing errors
1. Check that `VITE_SENTRY_DSN` is set
2. Check that Sentry is enabled in settings
3. Check browser console for Sentry initialization message
4. Verify network requests to Sentry are not blocked
### Sensitive data in reports
1. Check `beforeSend` hook in `instrument.ts`
2. Add new patterns to the scrubbing regex
3. Test with actual data to verify masking
### Performance impact
1. Reduce tracing sample rate in production
2. Disable session replay if not needed
3. Monitor Sentry quota usage
4. Adjust warning sampling rate
## Resources
- [Sentry React Documentation](https://docs.sentry.io/platforms/javascript/guides/react/)
- [Sentry Error Monitoring Best Practices](https://docs.sentry.io/product/error-monitoring/)
- [Sentry Session Replay](https://docs.sentry.io/product/session-replay/)
- [Sentry User Feedback](https://docs.sentry.io/product/user-feedback/)