feat(observability): integrate Sentry error + performance monitoring (frontend + backend)

Wire Sentry into the two user-facing tiers, fully opt-in via env var so
local dev and CI never phone home:

- backend (Django): sentry_sdk.init() in settings.py, guarded on SENTRY_DSN.
  The [django] extra auto-enables request/exception capture -- no middleware
  edits. Tunables: SENTRY_ENVIRONMENT, SENTRY_RELEASE,
  SENTRY_TRACES_SAMPLE_RATE (default 0.1), SENTRY_SEND_PII (default False).
  Adds sentry-sdk[django]==2.66.0 to requirements.txt.
- frontend (React CRA): Sentry.init() in src/index.js, guarded on
  REACT_APP_SENTRY_DSN, with browserTracing + replay integrations and a
  Sentry.ErrorBoundary fallback so render failures no longer white-screen.
  Adds @sentry/react.

Also documents the addition: Sentry badge + Observability notes in README,
ARCHITECTURE, DEPLOYMENT, and both frontend/backend READMEs; new env vars in
.env.example files.

Verified: manage.py check clean, 245 backend tests pass, frontend build OK.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hoangsonww

ARCHITECTURE.md

@@ -1293,6 +1293,17 @@ long-term observability target. The **current production deployment**
 on Vercel + Modal + Atlas runs a simpler, free-tier-only pipeline
 that backs the live `/metrics` endpoints on both services.
 
+Alongside that `/metrics` pipeline, **Sentry** provides opt-in error
+tracking and performance tracing for the two user-facing tiers — the React
+frontend (`@sentry/react`, initialised in `frontend/src/index.js`) and the
+Django API (`sentry-sdk[django]`, initialised in `backend/backend/settings.py`).
+Both initialise only when a DSN is present (`REACT_APP_SENTRY_DSN` /
+`SENTRY_DSN`), so local dev and CI stay offline; in production they stream
+unhandled exceptions plus a sampled slice of traces (default 10%) to the
+`unc-a4/moodify-app` project. The frontend also wraps the app in a Sentry
+`ErrorBoundary` so React render failures surface a fallback instead of a
+blank screen. PII (user id / IP / cookies) is **not** attached by default.
+
 #### Pipeline
 
 ```mermaid

DEPLOYMENT.md

@@ -62,6 +62,9 @@ Required envs for the **frontend** Vercel project (CRA build-time):
 
 * `REACT_APP_API_URL` → `https://moodify-backend-api.vercel.app`
 * `REACT_APP_MODAL_API_URL` → Modal service URL printed by `modal deploy`
+* _Optional:_ `REACT_APP_SENTRY_DSN` (+ `REACT_APP_SENTRY_ENVIRONMENT`,
+  `REACT_APP_SENTRY_TRACES_SAMPLE_RATE`) to turn on Sentry monitoring. Leave
+  unset to disable.
 
 Required envs for the **backend** Vercel project:
 
@@ -74,6 +77,10 @@ Required envs for the **backend** Vercel project:
   `WEBAUTHN_RP_NAME` (default `Moodify`), `WEBAUTHN_CHALLENGE_TTL_SECONDS`
   (default `300`). Defaults target `localhost` for local dev. If these don't
   match the domain the browser is on, passkey ceremonies fail in the browser.
+* **Sentry (optional):** `SENTRY_DSN` enables error + performance monitoring;
+  leave unset to disable. Tune with `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`,
+  `SENTRY_TRACES_SAMPLE_RATE` (default `0.1`), and `SENTRY_SEND_PII`
+  (default `False`).
 
 Required envs for the **mobile** Expo app (set via `eas env:create` or
 in `mobile/.env`):

README.md

@@ -99,6 +99,9 @@ are also used to visualize emotion trends and model performance. Users open reco
   <img src="https://img.shields.io/badge/Jenkins-D24939?style=for-the-badge&logo=jenkins&logoColor=white" alt="Jenkins" />
   <img src="https://img.shields.io/badge/GitHub_Actions-2088FF?style=for-the-badge&logo=githubactions&logoColor=white" alt="GitHub Actions" />
 
+  <!-- Observability / monitoring -->
+  <img src="https://img.shields.io/badge/Sentry-362D59?style=for-the-badge&logo=sentry&logoColor=white" alt="Sentry" />
+
   <!-- Hosting -->
   <img src="https://img.shields.io/badge/Vercel-000000?style=for-the-badge&logo=vercel&logoColor=white" alt="Vercel" />
   <img src="https://img.shields.io/badge/Modal-7B68EE?style=for-the-badge&logo=modal&logoColor=white" alt="Modal" />
@@ -909,6 +912,15 @@ container restarts and scale-to-zero. See
 and [`backend/README.md#sre-metrics`](backend/README.md#sre-metrics)
 for the full design (schema, resilience model, cost math).
 
+Alongside the aggregated `/metrics` surface, **Sentry** provides opt-in
+error tracking and performance tracing for the two user-facing tiers — the
+React frontend (`@sentry/react`) and the Django API (`sentry-sdk[django]`).
+Both initialise only when a DSN is set (`REACT_APP_SENTRY_DSN` /
+`SENTRY_DSN`), so local dev and CI stay offline; in production they stream
+unhandled exceptions plus a sampled slice of traces to the
+[`unc-a4/moodify-app`](https://unc-a4.sentry.io/settings/projects/moodify-app/)
+project.
+
 ### **Admin Interface Endpoints**
 
 | HTTP Method | Endpoint  | Description                                         |

backend/.env.example

@@ -45,3 +45,16 @@ CACHE_REDIS_URL=
 # --- Optional: API throttling rates ---
 THROTTLE_ANON=60/min
 THROTTLE_USER=240/min
+
+# --- Optional: Sentry error + performance monitoring ---
+# Leave SENTRY_DSN empty to disable (the SDK never initializes). Get the DSN
+# from the project settings at unc-a4.sentry.io/settings/projects/moodify-app.
+SENTRY_DSN=
+# Deploy stage label (defaults to production, or development when DEBUG=True).
+SENTRY_ENVIRONMENT=
+# Release/version tag for regression tracking (auto-detected from git if unset).
+SENTRY_RELEASE=
+# Fraction (0.0-1.0) of requests traced for performance. 0.1 = 10%.
+SENTRY_TRACES_SAMPLE_RATE=0.1
+# Attach user id / IP / cookies to events. Off by default for privacy.
+SENTRY_SEND_PII=False

backend/README.md

@@ -594,6 +594,11 @@ in your Vercel project's Environment Variables for production.
 | `METRICS_TTL_DAYS` | no | Native TTL for raw metric events. Default `30`. |
 | `ADMIN_METRICS_TOKEN` | no | Bearer token that unlocks `GET /api/metrics/`. Falls back to `MODAL_SERVICE_TOKEN` so a single secret unlocks both `/metrics` surfaces. |
 | `CACHE_REDIS_URL` | no | If set, use Redis (e.g. Upstash) instead of LocMem cache |
+| `SENTRY_DSN` | no | Enable Sentry error + performance monitoring. Empty ⇒ SDK never initialises (local/CI stay offline). DSN from the `unc-a4/moodify-app` project. |
+| `SENTRY_ENVIRONMENT` | no | Deploy-stage label on events. Default `production` (or `development` when `DEBUG=True`). |
+| `SENTRY_RELEASE` | no | Release/version tag for regression tracking. Auto-detected from git if unset. |
+| `SENTRY_TRACES_SAMPLE_RATE` | no | Fraction (0.0–1.0) of requests traced for performance. Default `0.1`. |
+| `SENTRY_SEND_PII` | no | Attach user id / IP / cookies to events. Default `False` (privacy-preserving). |
 
 ---
 

backend/backend/settings.py

@@ -23,6 +23,32 @@
 # service verifies them with the same key. Keep it in sync across both.
 JWT_SIGNING_KEY = config("JWT_SIGNING_KEY", default=SECRET_KEY)
 
+# --- Error monitoring (Sentry) --------------------------------------------
+# Streams unhandled exceptions + a sampled slice of performance traces to
+# Sentry (project: unc-a4/moodify-app). Entirely opt-in: with no SENTRY_DSN
+# the SDK never initializes, so local dev and CI stay fully offline. The
+# [django] extra auto-wires request/exception capture -- no middleware edits.
+_SENTRY_DSN = config("SENTRY_DSN", default="")
+if _SENTRY_DSN:
+    import sentry_sdk
+
+    sentry_sdk.init(
+        dsn=_SENTRY_DSN,
+        # Label events by deploy stage; falls back to DEBUG when unset.
+        environment=config(
+            "SENTRY_ENVIRONMENT",
+            default="development" if DEBUG else "production",
+        ),
+        # Git SHA / version tag for regression tracking (auto-detected if unset).
+        release=config("SENTRY_RELEASE", default=None),
+        # Fraction of requests captured as performance transactions. 10% keeps
+        # trace volume (and quota) sane under real traffic; raise for debugging.
+        traces_sample_rate=config("SENTRY_TRACES_SAMPLE_RATE", default=0.1, cast=float),
+        # Do NOT attach user id / IP / cookies unless explicitly opted in --
+        # this API handles auth material, so default to privacy-preserving.
+        send_default_pii=config("SENTRY_SEND_PII", default=False, cast=bool),
+    )
+
 # --- MongoDB (the only datastore) -----------------------------------------
 # connect() is lazy -- it does not open a socket until the first query.
 # maxPoolSize is kept small: on a serverless host each instance keeps its

backend/requirements.txt

@@ -34,3 +34,9 @@ python-dotenv==1.0.1
 whitenoise==6.7.0
 gunicorn==23.0.0
 tzdata==2024.2
+
+# --- Error monitoring (Sentry) ---
+# The [django] extra auto-enables DjangoIntegration -- the only wiring is a
+# single sentry_sdk.init() in settings.py, which no-ops unless SENTRY_DSN is
+# set, so local dev and CI never phone home.
+sentry-sdk[django]==2.66.0

frontend/.env.example

@@ -7,3 +7,13 @@ REACT_APP_API_URL=https://your-django-api.vercel.app
 
 # Modal ML inference service (speech + facial emotion, direct upload).
 REACT_APP_MODAL_API_URL=https://your-org--moodify-inference-inferenceservice-web.modal.run
+
+# --- Optional: Sentry error + performance monitoring ---
+# Leave REACT_APP_SENTRY_DSN empty to disable (the SDK never initializes).
+# Get the DSN from unc-a4.sentry.io/settings/projects/moodify-app. Only the
+# public DSN belongs here -- it is safe to expose in a client build.
+REACT_APP_SENTRY_DSN=
+# Deploy stage label (defaults to NODE_ENV when unset).
+REACT_APP_SENTRY_ENVIRONMENT=
+# Fraction (0.0-1.0) of transactions traced for performance. 0.1 = 10%.
+REACT_APP_SENTRY_TRACES_SAMPLE_RATE=0.1

frontend/README.md

@@ -488,6 +488,14 @@ sequenceDiagram
    Environment Variables panel (Production / Preview / Development) and
    redeploy - `frontend/src/config.js` reads them at build time.
 
+   Optionally, enable **Sentry** error + performance monitoring by also
+   setting `REACT_APP_SENTRY_DSN` (from the `unc-a4/moodify-app` project).
+   Leave it empty to disable — `frontend/src/index.js` only initialises the
+   SDK when a DSN is present, so local dev and CI builds send nothing.
+   `REACT_APP_SENTRY_ENVIRONMENT` and `REACT_APP_SENTRY_TRACES_SAMPLE_RATE`
+   (default `0.1`) tune the stage label and trace sampling. Only the public
+   DSN belongs in the client build.
+
 ### Running the Application
 
 To start the development server, run the following command: