# Sentry Setup & Configuration

This document describes how to configure Sentry for crash reporting in Yorvana.

## 1. Local Configuration

Sentry DSNs are injected via `BuildConfig` from `local.properties`. This file is gitignored to prevent leaking keys.

Add the following to your `local.properties`:

```properties
sentry.dsn.debug=https://your-debug-dsn@sentry.io/project
sentry.dsn.release=https://your-release-dsn@sentry.io/project
```

If these keys are missing, the app will build but Sentry initialization will be skipped.

## 2. Project Registration

1. Create a new Android project in Sentry.
2. Under **Project Settings > Client Keys (DSN)**, find your DSN.
3. It is recommended to use separate Sentry projects for `debug` and `release` to keep test data separate from production data.

## 3. Privacy & Compliance

Yorvana is privacy-first. Sentry is initialized with strict privacy settings:

- **Opt-in only**: Crash reporting is disabled by default.
- **Minimal data**: We do not attach screenshots, view hierarchies, or breadcrumbs by default.
- **PII Stripping**: The `beforeSend` hook in `YorvanaApplication` explicitly clears user and server name fields.

## 4. User-Initiated Feedback (Manual Submission)

When a user submits a bug report or suggestion via the "Report Bug" screen, the app may use Sentry to transmit this manual feedback even if global crash reporting is disabled.

- **Explicit Action**: This only occurs when the user manually fills out the form and taps "Submit".
- **One-Shot Initialization**: Sentry is initialized specifically for the submission and immediately closed thereafter.
- **Traceability**: A breadcrumb `User-initiated feedback submission (crash reporting disabled)` is automatically attached to these events. This allows triage to distinguish between automated crash reports and intentional user feedback.

## 5. Spike Protection & Rate Limits

To prevent unexpected costs or overwhelming the backend:

1. **Enable Spike Protection**: In Sentry Project Settings, enable Spike Protection to automatically drop events if a sudden surge occurs.
2. **Per-DSN Rate Limits**: Set a monthly or daily cap on the number of events accepted per DSN.
3. **Sampling**: The `sampleRate` is currently set to `1.0` (100% of errors). If the volume becomes too high, this can be reduced in `YorvanaApplication`.

## 6. DSN Rotation

If a DSN is compromised:

1. Generate a new key in the Sentry dashboard.
2. Update `local.properties` (for local development) or CI/CD secrets (for production builds).
3. Revoke the old key in Sentry.