Merge PR #5: Wire Sentry + PostHog observability + EU cookie consent banner

Mirrors HelpmateAI's observability stack into AI Job Agent. Sentry (jobagent-backend + jobagent-frontend) + PostHog (shared free-tier project, product=jobagent tag) + GDPR cookie banner. Source-map upload via SENTRY_AUTH_TOKEN. Code mappings live for both projects. CI green on b53d8c1 after the leaky-detail allowlist line-drift fix.

Author: LEANDERANTONY

.env.example

@@ -133,3 +133,36 @@ AIJOBAGENT_LEMONSQUEEZY_PRODUCT_VARIANT_BUSINESS=
 NEXT_PUBLIC_LEMONSQUEEZY_STORE_ID=
 NEXT_PUBLIC_LEMONSQUEEZY_PRODUCT_VARIANT_PRO=
 NEXT_PUBLIC_LEMONSQUEEZY_PRODUCT_VARIANT_BUSINESS=
+
+## Observability — Sentry (error tracking + tracing + AI agents
+## monitoring + Logs + Crons) + PostHog (product analytics +
+## session replay + LLM analytics). All optional; the integrations
+## are no-ops when their DSN / API key is empty, so dev environments
+## and CI don't have to carry the secrets.
+##
+## Backend (server-only):
+SENTRY_DSN=
+SENTRY_TRACES_SAMPLE_RATE=0.1
+SENTRY_PROFILES_SAMPLE_RATE=0.05
+SENTRY_SEND_DEFAULT_PII=false
+## Falls back to BackendSettings.service_version when unset.
+SENTRY_RELEASE=
+POSTHOG_API_KEY=
+POSTHOG_HOST=https://eu.i.posthog.com
+## Tag attached to every Sentry event + PostHog server-side event
+## so dashboards can slice production from staging / preview deploys.
+AIJOBAGENT_ENVIRONMENT=development
+
+## Source-map upload via withSentryConfig (frontend/next.config.ts).
+## Generate at Sentry -> Settings -> Auth Tokens with project:releases
+## + project:read scopes. Vercel's Sentry integration auto-provisions
+## this; if you install that, leave this blank.
+SENTRY_AUTH_TOKEN=
+
+## Frontend (Next.js inlines NEXT_PUBLIC_* into the JS bundle):
+NEXT_PUBLIC_SENTRY_DSN=
+NEXT_PUBLIC_SENTRY_ENVIRONMENT=development
+NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0.1
+NEXT_PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1.0
+NEXT_PUBLIC_POSTHOG_KEY=
+NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

backend/app.py

@@ -1,10 +1,17 @@
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from slowapi.errors import RateLimitExceeded
 from slowapi.middleware import SlowAPIMiddleware
 
 from backend.config import get_backend_settings
+from backend.observability import (
+    initialize_observability,
+    shutdown_observability,
+)
 from backend.rate_limit import limiter, rate_limit_exceeded_handler
 from backend.routers.auth import router as auth_router
 from backend.routers.billing import router as billing_router
@@ -16,9 +23,35 @@
 
 settings = get_backend_settings()
 
+# Initialize Sentry + PostHog BEFORE ``FastAPI()`` so Sentry's ASGI
+# middleware wraps the app at construction time. Both are no-ops when
+# their respective DSN / API key env vars are unset, so the order is
+# safe in environments that haven't wired the integration on yet
+# (local dev, CI, the test suite). See ``backend/observability.py``
+# for the bootstrap details.
+initialize_observability(settings)
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    # ``yield`` is the boundary: startup happens above (we already
+    # initialized observability at import time, so there's no setup
+    # work to do here), shutdown happens below.
+    try:
+        yield
+    finally:
+        # Flush the PostHog buffer on graceful termination. PostHog also
+        # registers its own atexit handler, but explicit drain via lifespan
+        # ensures buffered events leave the process even when the worker
+        # is killed by a signal that the interpreter atexit chain doesn't
+        # reach (eg. SIGTERM on a container redeploy).
+        shutdown_observability()
+
+
 app = FastAPI(
     title=settings.service_name,
     version=settings.service_version,
+    lifespan=_lifespan,
 )
 
 
@@ -85,6 +118,29 @@ def root():
     }
 
 
+@app.get("/health/sentry-debug")
+def sentry_debug() -> None:
+    """Raise an unhandled exception so Sentry sees the issue end-to-end.
+
+    Used once at deploy time to confirm the DSN, environment, and
+    release tag are wired. The route returns no JSON — Sentry's
+    FastAPI integration catches the raise, ships the event, and
+    FastAPI's default 500 handler returns "Internal Server Error" to
+    the caller. There is intentionally no auth on this route: it must
+    be callable from anywhere with curl. Remove or gate it behind a
+    feature flag if your threat model objects.
+
+    Path is OUTSIDE ``settings.api_prefix`` (no /api/) so it doesn't
+    accidentally appear in the workspace-API surface that auth /
+    middleware paths assume. Matches HelpmateAI's convention exactly.
+    """
+    # ``division by zero`` is the canonical Sentry-tutorial sample;
+    # keeping it deliberately recognizable so anyone reading the issue
+    # title in Sentry knows it's a smoke test, not a real bug.
+    division_by_zero = 1 / 0  # noqa: F841 — intentional crash for Sentry verification
+    return None
+
+
 app.include_router(health_router, prefix=settings.api_prefix)
 app.include_router(jobs_router, prefix=settings.api_prefix)
 app.include_router(jobs_admin_router, prefix=settings.api_prefix)

backend/config.py

@@ -29,6 +29,20 @@ class BackendSettings:
     auth_cookie_domain: str
     auth_cookie_secure: bool
     auth_cookie_samesite: str
+    # Observability — Sentry + PostHog. All four are optional; when the
+    # DSN / API key is empty the observability bootstrap is a no-op (no
+    # network, no SDK init). ``environment`` and ``release`` are used
+    # by both vendors to slice events by deploy. ``release`` defaults
+    # to the service_version when unset so a forgotten SENTRY_RELEASE
+    # still groups events by something stable.
+    sentry_dsn: str
+    sentry_traces_sample_rate: float
+    sentry_profiles_sample_rate: float
+    sentry_send_default_pii: bool
+    sentry_release: str
+    posthog_api_key: str
+    posthog_host: str
+    observability_environment: str
 
 
 def _parse_bool(value: str, default: bool) -> bool:
@@ -42,6 +56,21 @@ def _parse_bool(value: str, default: bool) -> bool:
     return default
 
 
+def _parse_float(value: str, default: float) -> float:
+    """Lenient float parser for sample-rate env vars.
+
+    Empty / malformed values fall back to ``default`` rather than
+    raising — the observability layer must never crash backend boot
+    just because someone fat-fingered a sample rate."""
+    stripped = (value or "").strip()
+    if not stripped:
+        return default
+    try:
+        return float(stripped)
+    except (TypeError, ValueError):
+        return default
+
+
 def get_backend_settings() -> BackendSettings:
     frontend_app_url = (
         os.getenv("FRONTEND_APP_URL", "http://localhost:3000").strip()
@@ -70,9 +99,27 @@ def get_backend_settings() -> BackendSettings:
         raw_samesite if raw_samesite in {"lax", "strict", "none"} else "lax"
     )
 
+    # Observability — never raise from env parsing; missing values
+    # collapse to safe defaults so a fresh checkout boots without any
+    # Sentry / PostHog config at all (local dev, CI). The
+    # observability bootstrap then sees an empty DSN/key and bails.
+    service_version = "0.2.0"
+    sentry_dsn = (os.getenv("SENTRY_DSN") or "").strip()
+    sentry_traces_sample_rate = _parse_float(os.getenv("SENTRY_TRACES_SAMPLE_RATE", ""), 0.1)
+    sentry_profiles_sample_rate = _parse_float(os.getenv("SENTRY_PROFILES_SAMPLE_RATE", ""), 0.05)
+    sentry_send_default_pii = _parse_bool(os.getenv("SENTRY_SEND_DEFAULT_PII", ""), False)
+    sentry_release = (os.getenv("SENTRY_RELEASE") or service_version).strip() or service_version
+    posthog_api_key = (os.getenv("POSTHOG_API_KEY") or "").strip()
+    posthog_host = (os.getenv("POSTHOG_HOST") or "https://eu.i.posthog.com").strip()
+    observability_environment = (
+        os.getenv("AIJOBAGENT_ENVIRONMENT")
+        or os.getenv("ENVIRONMENT")
+        or "development"
+    ).strip()
+
     return BackendSettings(
         service_name="AI Job Application Agent Backend",
-        service_version="0.2.0",
+        service_version=service_version,
         api_prefix="/api",
         backend_base_url=JOB_BACKEND_BASE_URL,
         frontend_app_url=frontend_app_url,
@@ -84,4 +131,12 @@ def get_backend_settings() -> BackendSettings:
         auth_cookie_domain=auth_cookie_domain,
         auth_cookie_secure=auth_cookie_secure,
         auth_cookie_samesite=auth_cookie_samesite,
+        sentry_dsn=sentry_dsn,
+        sentry_traces_sample_rate=sentry_traces_sample_rate,
+        sentry_profiles_sample_rate=sentry_profiles_sample_rate,
+        sentry_send_default_pii=sentry_send_default_pii,
+        sentry_release=sentry_release,
+        posthog_api_key=posthog_api_key,
+        posthog_host=posthog_host,
+        observability_environment=observability_environment,
     )