# Sentry Error Forwarding

## Objective

Send real application errors to Sentry with clean context and grouping worth acting on.

Server and client error reporting into Sentry, with release and environment tagging, scrubbing, and deliberate noise control.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find the app's existing error handling paths and route from there. Reporting belongs where errors are already caught and logged, not sprinkled into individual controllers and components.
2. Separate genuine faults from expected outcomes. Validation failures, permission denials, not-found responses, and cancelled requests are normal behaviour and must not be reported as crashes, or the signal is buried within a day.
3. Scrub every event before it leaves the process: authorisation headers, tokens, passwords, payment details, request bodies, query strings, and any personal data the app is not permitted to send to a third party. Attach an internal user or account identifier instead of a name or an email address.
4. Tag every event with the deployed release and the environment, taken from the same source the deploy pipeline already uses, so a spike can be traced to a specific ship. Keep the credentials for the reporting endpoint in server configuration and use the separate client-side key for browser reporting.
5. Leave grouping to the provider's default and override the fingerprint only for the specific cases where it is demonstrably wrong — a wrapper exception that collapses thousands of distinct faults into one, or a message carrying an identifier that splits one fault into thousands.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Events routinely carry secrets and personal data by accident, through request headers, form bodies, and exception messages that interpolate a value. Scrub at the point of capture, and default to dropping unknown fields rather than sending them.
- A custom fingerprint applied broadly is worse than the default, because it merges unrelated faults into a single unactionable issue. Set one only where the default grouping has been shown to fail, and record why.
- Release and environment must be set identically everywhere, including background jobs and the browser build. A missing release makes a regression impossible to attribute to a deploy.
- Expected errors reported as crashes destroy the error budget and train the team to ignore alerts. Classify them explicitly and let them stay in ordinary logs.
- Linking an error to a trace is useful, but reporting the same fault at every layer it bubbles through floods the project with duplicates. Report once, at the outermost handler, and carry the trace identifier rather than re-raising a new event per frame.
- A single failing endpoint can generate an enormous burst and exhaust the account's quota within minutes. Sample repetitive events and rate-limit reporting per issue rather than sending everything.
- The reporting service itself will be unavailable or slow. Sending must never block a user request or fail one; drop or queue the event and carry on.
- Errors thrown during startup, or inside the reporting path itself, must not recurse. Guard the reporter so a failure to report cannot generate another report.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Errors are reported from the app's existing central handlers rather than from scattered call sites.
- [ ] Expected validation, permission, and not-found outcomes do not appear as reported errors.
- [ ] No secret, credential, or personal data field is present in any forwarded event, verified against a real captured payload.
- [ ] Every event carries a release and an environment consistent with the deploy pipeline, in both server and browser reporting.
- [ ] Custom fingerprints exist only where default grouping was inadequate, and each one is documented.
- [ ] A burst of identical errors is sampled and rate-limited, and reporting never blocks or fails a user request.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.