Source: https://www.hype-stack.dev/docs/development/observability

# Observability

Sentry is an optional paid-provider integration. It is not required to run the free template. Use this page when your
project has Sentry installed and you have your own provider keys.

## Sentry

When configured, Sentry captures unhandled errors, performance traces, and request context.

### Backend

When `SENTRY_DSN` is set, the centralized error middleware reports **unexpected** errors automatically. You do not add
`Sentry.captureException()` in route handlers for ordinary failures.

| Reported to Sentry                         | Returned to the client only                               |
| ------------------------------------------ | --------------------------------------------------------- |
| Unexpected / infrastructure errors         | Typed application errors (404, validation, auth failures) |
| Unhandled exceptions bubbling to `onError` | Expected business outcomes                                |

That split matters: if you wrap logic in local `try/catch` and swallow the error, you also skip Sentry. Throw typed
errors and let the middleware format the response.

### Frontend

When `VITE_SENTRY_DNS` is set (the template spells it `DNS`), Sentry initializes in the app entry and captures:

- Unhandled exceptions and promise rejections
- React component errors via the error boundary
- Performance traces for navigation and API calls

### Configuration

```bash
# Backend (apps/backend/.env)
SENTRY_DSN=https://your-dsn@sentry.io/123

# Frontend, admin, extension (apps/<app>/.env)
VITE_SENTRY_DNS=https://your-dsn@sentry.io/456
VITE_SENTRY_AUTH_TOKEN=sntrys_...   # only for uploading source maps at build time

# Mobile (apps/mobile/.env)
EXPO_PUBLIC_SENTRY_DNS=https://your-dsn@sentry.io/789
```

Use separate Sentry projects per app when you can. It keeps noise and release tracking clearer.

## Disabling in development

Both services check for the presence of their env variables. Leave them empty in your `.env` file to disable tracking
locally.

## Structured logs

The backend logger (`apps/backend/src/libs/logger`) is the place for operational messages. Prefer logging through that
helper rather than `console.log` in features. Unexpected failures still belong in the error middleware path so they can
reach Sentry.

## Related

- [Backend overview](/docs/backend) for the error middleware role
- [Going to production](/docs/getting-started/going-to-production)
- [Env variables](/docs/backend/env-variables)