@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/python/error-monitoring.md

@@ -0,0 +1,292 @@
+# Error Monitoring — Sentry Python SDK
+
+> Minimum SDK: `sentry-sdk` 1.x+ (2.x for `new_scope()`, `get_isolation_scope()`)
+
+## Configuration
+
+Key `sentry_sdk.init()` options for error monitoring:
+
+| Option                    | Type            | Default              | Purpose                                         |
+| ------------------------- | --------------- | -------------------- | ----------------------------------------------- |
+| `dsn`                     | `str`           | env `SENTRY_DSN`     | Data Source Name; SDK disabled if empty         |
+| `environment`             | `str`           | `"production"`       | Deployment environment tag                      |
+| `release`                 | `str`           | env `SENTRY_RELEASE` | App version string                              |
+| `sample_rate`             | `float`         | `1.0`                | Fraction of error events to send (0.0–1.0)      |
+| `send_default_pii`        | `bool`          | `False`              | Include IPs, cookies, sessions                  |
+| `attach_stacktrace`       | `bool`          | `False`              | Add stack traces to `capture_message()`         |
+| `max_breadcrumbs`         | `int`           | `100`                | Max breadcrumbs per event                       |
+| `ignore_errors`           | `list`          | `[]`                 | Exception types to never report                 |
+| `before_send`             | `callable`      | `None`               | Mutate or drop error events before sending      |
+| `before_breadcrumb`       | `callable`      | `None`               | Mutate or drop breadcrumbs                      |
+| `event_scrubber`          | `EventScrubber` | `None`               | Denylist-based PII scrubber                     |
+| `include_local_variables` | `bool`          | `True`               | Capture stack-frame local variable values       |
+| `max_request_body_size`   | `str`           | `"medium"`           | `"never"` / `"small"` / `"medium"` / `"always"` |
+
+## Code Examples
+
+### Basic setup
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    environment="production",
+    release="my-app@1.0.0",
+    sample_rate=1.0,
+    send_default_pii=False,
+    max_breadcrumbs=100,
+)
+```
+
+### Capturing exceptions and messages
+
+```python
+import sentry_sdk
+
+# Capture current exception (inside except block — reads sys.exc_info())
+try:
+    risky_operation()
+except Exception:
+    sentry_sdk.capture_exception()
+
+# Capture explicit exception object
+try:
+    risky_operation()
+except Exception as e:
+    sentry_sdk.capture_exception(e)
+    raise  # re-raise after capturing
+
+# Capture a plain message
+sentry_sdk.capture_message("Payment webhook received unexpected payload")
+sentry_sdk.capture_message("Rate limit approaching", level="warning")
+
+# Capture a fully manual event
+sentry_sdk.capture_event({
+    "message": "Billing failure",
+    "level": "error",
+    "tags": {"payment.method": "stripe"},
+    "fingerprint": ["billing-charge-failure"],
+})
+```
+
+### Automatic capture by framework
+
+Framework integrations are **auto-enabled** when installed — no `integrations=[...]`
+needed for most:
+
+```python
+# Django — unhandled view exceptions auto-captured
+import sentry_sdk
+sentry_sdk.init(dsn="...")   # DjangoIntegration auto-enabled
+
+# Flask — unhandled route exceptions auto-captured
+from flask import Flask
+import sentry_sdk
+sentry_sdk.init(dsn="...")   # FlaskIntegration auto-enabled
+app = Flask(__name__)
+
+# FastAPI — unhandled endpoint exceptions auto-captured
+import sentry_sdk
+sentry_sdk.init(dsn="...")   # StarletteIntegration + FastApiIntegration auto-enabled
+
+# Celery — task exceptions auto-captured
+import sentry_sdk
+sentry_sdk.init(dsn="...")   # CeleryIntegration auto-enabled
+```
+
+### Scope management (SDK 2.x)
+
+Three scope layers merge when sending events:
+
+| Scope         | Lifetime           | Use for                        |
+| ------------- | ------------------ | ------------------------------ |
+| **Global**    | Process lifetime   | App-wide tags, server metadata |
+| **Isolation** | One request / task | Per-request user, tags         |
+| **Current**   | One span           | Per-span metadata              |
+
+```python
+import sentry_sdk
+
+# Per-request user (isolation scope — fresh per HTTP request with web integrations)
+scope = sentry_sdk.get_isolation_scope()
+scope.set_user({"id": "user_42", "email": "alice@example.com"})
+scope.set_tag("request.id", "req_abc123")
+
+# Temporary forked scope — changes don't leak out
+with sentry_sdk.new_scope() as scope:
+    scope.set_tag("payment.retry_attempt", "3")
+    scope.set_context("charge", {"amount": 9900, "currency": "USD"})
+    scope.fingerprint = ["payment-processing-error"]
+    sentry_sdk.capture_exception(some_error)
+# ← scope reverts here
+```
+
+### Context enrichment
+
+```python
+import sentry_sdk
+
+# Tags — indexed and searchable; max key 32 chars, value 200 chars
+sentry_sdk.set_tag("page.locale", "de-at")
+sentry_sdk.set_tags({"feature.flag": "new_checkout_v2", "plan": "enterprise"})
+
+# User identity
+sentry_sdk.set_user({
+    "id": "user_42",
+    "username": "alice_wonder",
+    "email": "alice@example.com",
+    "ip_address": "{{auto}}",    # Sentry infers from connection
+})
+sentry_sdk.set_user(None)        # clear user (e.g., on logout)
+
+# Structured context objects (not searchable, visible in event detail)
+sentry_sdk.set_context("payment", {
+    "provider": "stripe",
+    "amount": 9900,
+    "currency": "USD",
+})
+
+# Breadcrumbs
+sentry_sdk.add_breadcrumb(
+    type="http",
+    category="auth",
+    message="User authenticated via OAuth2",
+    level="info",
+    data={"provider": "google"},
+)
+```
+
+### `before_send` hook — filtering and scrubbing
+
+```python
+import sentry_sdk
+
+def before_send(event, hint):
+    exc_info = hint.get("exc_info")
+
+    # Drop non-actionable exceptions
+    if exc_info and issubclass(exc_info[0], (KeyboardInterrupt, SystemExit)):
+        return None
+
+    # Scrub sensitive HTTP headers
+    headers = event.get("request", {}).get("headers", {})
+    for h in ("Authorization", "Cookie", "X-Api-Key"):
+        if h in headers:
+            headers[h] = "[Filtered]"
+
+    # Scrub local variables
+    for exc in event.get("exception", {}).get("values", []):
+        for frame in exc.get("stacktrace", {}).get("frames", []):
+            for key in ("password", "token", "secret"):
+                frame.get("vars", {}).pop(key, None)
+
+    # Custom fingerprinting
+    if exc_info and isinstance(exc_info[1], TimeoutError):
+        event["fingerprint"] = ["network-timeout"]
+
+    return event
+
+sentry_sdk.init(dsn="...", before_send=before_send)
+```
+
+### Fingerprinting (custom grouping)
+
+```python
+import sentry_sdk
+
+# Static fingerprint via scope
+with sentry_sdk.new_scope() as scope:
+    scope.fingerprint = ["database-connection-failure"]
+    sentry_sdk.capture_exception(db_error)
+
+# Extend default grouping
+with sentry_sdk.new_scope() as scope:
+    scope.fingerprint = ["{{ default }}", "stripe-payment-failure"]
+    sentry_sdk.capture_exception(payment_error)
+
+# Dynamic fingerprint in before_send
+def before_send(event, hint):
+    exc_info = hint.get("exc_info")
+    if exc_info and hasattr(exc_info[1], "status_code"):
+        code = exc_info[1].status_code
+        if code >= 500:
+            event["fingerprint"] = ["http-server-error", str(code)]
+    return event
+```
+
+### PII scrubbing with EventScrubber
+
+```python
+import sentry_sdk
+from sentry_sdk.scrubber import EventScrubber, DEFAULT_DENYLIST
+
+sentry_sdk.init(
+    dsn="...",
+    send_default_pii=False,
+    event_scrubber=EventScrubber(
+        denylist=DEFAULT_DENYLIST + ["stripe_key", "internal_secret", "ssn"],
+        recursive=True,   # deep-scan nested dicts (has performance cost)
+    ),
+)
+```
+
+### Exception Groups (Python 3.11+)
+
+```python
+import sentry_sdk
+
+# ExceptionGroup sub-exceptions appear as linked entries in Sentry UI
+try:
+    raise ExceptionGroup(
+        "Batch job failures",
+        [ValueError("Bad record #1"), KeyError("Missing field in record #5")],
+    )
+except* ValueError as eg:
+    sentry_sdk.capture_exception(eg)
+except* KeyError as eg:
+    sentry_sdk.capture_exception(eg)
+```
+
+### Advanced: Framework middleware pattern
+
+```python
+import sentry_sdk
+from flask import Flask
+
+app = Flask(__name__)
+sentry_sdk.init(dsn="...")
+
+@app.before_request
+def set_sentry_user():
+    scope = sentry_sdk.get_isolation_scope()
+    user = get_current_user()
+    if user:
+        scope.set_user({"id": str(user.id), "username": user.username})
+        scope.set_tag("user.plan", user.plan)
+```
+
+## Best Practices
+
+- Set `send_default_pii=False` (default) — add explicit PII scrubbing via `before_send`
+  or `EventScrubber`
+- Use `get_isolation_scope()` for per-request data; use `new_scope()` for temporary
+  isolated context
+- Avoid `set_extra()` (deprecated) — use `set_context()` for structured data
+- Prefer `set_tag()` for data you want to filter on; `set_context()` for detail-only
+  data
+- Use `ignore_errors=[...]` for exceptions you never want reported (e.g.,
+  `KeyboardInterrupt`)
+- Set `in_app_include=["my_package"]` to correctly mark your frames as in-app in
+  tracebacks
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Events not appearing in Sentry              | Verify DSN, check `debug=True` output, ensure `sentry_sdk.init()` is called before app startup |
+| User/tag data missing from events           | Set scope data before the exception occurs; check isolation vs current scope                   |
+| PII appearing in events                     | Set `send_default_pii=False` and add `EventScrubber` with your denylist                        |
+| `capture_exception()` is a no-op            | Must be called inside an `except` block or pass the exception explicitly                       |
+| Breadcrumbs missing                         | Check `max_breadcrumbs` setting and `before_breadcrumb` hook                                   |
+| `push_scope()` / `configure_scope()` errors | Migrate to `new_scope()` / `get_isolation_scope()` (SDK 2.x)                                   |

package/skills/sentry/references/sdks/python/index.md

@@ -0,0 +1,361 @@
+# Sentry Python SDK
+
+Opinionated wizard that scans your Python project and guides you through complete Sentry
+setup.
+
+> **Note:** SDK versions and APIs below reflect Sentry docs at time of writing
+> (sentry-sdk 2.x). Always verify against
+> [docs.sentry.io/platforms/python/](https://docs.sentry.io/platforms/python/) before
+> implementing.
+
+---
+
+## Phase 1: Detect
+
+Run these commands to understand the project before making recommendations:
+
+```bash
+# Check existing Sentry
+grep -i sentry requirements.txt pyproject.toml setup.cfg setup.py 2>/dev/null
+
+# Detect web framework
+grep -rE "django|flask|fastapi|starlette|aiohttp|tornado|quart|falcon|sanic|bottle|pyramid" \
+  requirements.txt pyproject.toml 2>/dev/null
+
+# Detect task queues
+grep -rE "celery|rq|huey|arq|dramatiq" requirements.txt pyproject.toml 2>/dev/null
+
+# Detect logging libraries
+grep -E "loguru" requirements.txt pyproject.toml 2>/dev/null
+
+# Detect AI libraries
+grep -rE "openai|anthropic|langchain|huggingface|google-genai|pydantic-ai|litellm" \
+  requirements.txt pyproject.toml 2>/dev/null
+
+# Detect schedulers / crons
+grep -rE "celery|apscheduler|schedule|crontab" requirements.txt pyproject.toml 2>/dev/null
+
+# OpenTelemetry tracing — check for SDK + instrumentations
+grep -rE "opentelemetry-sdk|opentelemetry-instrumentation|opentelemetry-distro" \
+  requirements.txt pyproject.toml 2>/dev/null
+grep -rn "TracerProvider\|trace\.get_tracer\|start_as_current_span" \
+  --include="*.py" 2>/dev/null | head -5
+
+# Check for companion frontend
+ls frontend/ web/ client/ ui/ static/ templates/ 2>/dev/null
+```
+
+**What to note:**
+
+- Is `sentry-sdk` already in requirements?
+  If yes, check if `sentry_sdk.init()` is present — may just need feature config.
+- Which framework? (Determines where to place `sentry_sdk.init()`.)
+- Which task queue? (Celery needs dual-process init; RQ needs a settings file.)
+- AI libraries? (OpenAI, Anthropic, LangChain are auto-instrumented.)
+- OpenTelemetry tracing?
+  (Use OTLP path instead of native tracing.)
+- Companion frontend? (Triggers Phase 4 cross-link.)
+
+---
+
+## Phase 2: Recommend
+
+Based on what you found, present a concrete proposal.
+Don’t ask open-ended questions — lead with a recommendation:
+
+**Route from OTel detection:**
+
+- **OTel tracing detected** (`opentelemetry-sdk` / `opentelemetry-distro` in
+  requirements, or `TracerProvider` in source) → use OTLP path: `OTLPIntegration()`; do
+  **not** set `traces_sample_rate`; Sentry links errors to OTel traces automatically
+
+**Always recommended (core coverage):**
+
+- ✅ **Error Monitoring** — captures unhandled exceptions, supports `ExceptionGroup`
+  (Python 3.11+)
+- ✅ **Logging** — Python `logging` stdlib auto-captured; enhanced if Loguru detected
+
+**Recommend when detected:**
+
+- ✅ **Tracing** — HTTP framework detected (Django/Flask/FastAPI/etc.)
+- ✅ **AI Monitoring** — OpenAI/Anthropic/LangChain/etc.
+  detected (auto-instrumented, zero config)
+- ⚡ **Profiling** — production apps where performance matters; **not available with OTLP
+  path**
+- ⚡ **Crons** — Celery Beat, APScheduler, or cron patterns detected
+- ⚡ **Metrics** — business KPIs, SLO tracking
+
+**Recommendation matrix:**
+
+| Feature          | Recommend when …                                                                                                                       | Reference               |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Error Monitoring | **Always** — non-negotiable baseline                                                                                                   | `./error-monitoring.md` |
+| OTLP Integration | OTel tracing detected — **replaces** native Tracing                                                                                    | `./tracing.md`          |
+| Tracing          | Django/Flask/FastAPI/AIOHTTP/etc. detected; **skip if OTel tracing detected**                                                          | `./tracing.md`          |
+| Profiling        | Production + performance-sensitive workload; **skip if OTel tracing detected** (requires `traces_sample_rate`, incompatible with OTLP) | `./profiling.md`        |
+| Logging          | Always (stdlib); enhanced for Loguru                                                                                                   | `./logging.md`          |
+| Metrics          | Business events or SLO tracking needed                                                                                                 | `./metrics.md`          |
+| Crons            | Celery Beat, APScheduler, or cron patterns                                                                                             | `./crons.md`            |
+| AI Monitoring    | OpenAI/Anthropic/LangChain/etc. detected                                                                                               | `./ai-monitoring.md`    |
+
+**OTel tracing detected:** _“I see OpenTelemetry tracing in the project.
+I recommend Sentry’s OTLP integration for tracing (via your existing OTel setup) + Error
+Monitoring + Sentry Logging [+ Metrics/Crons/AI Monitoring if applicable]. Shall I
+proceed?”_
+
+**No OTel:** _“I recommend Error Monitoring + Tracing [+ Logging if applicable]. Want
+Profiling, Crons, or AI Monitoring too?”_
+
+---
+
+## Phase 3: Guide
+
+### Install
+
+```bash
+# Core SDK (always required)
+pip install sentry-sdk
+
+# Optional extras (install only what matches detected framework):
+pip install "sentry-sdk[django]"
+pip install "sentry-sdk[flask]"
+pip install "sentry-sdk[fastapi]"
+pip install "sentry-sdk[celery]"
+pip install "sentry-sdk[aiohttp]"
+pip install "sentry-sdk[tornado]"
+
+# Multiple extras:
+pip install "sentry-sdk[django,celery]"
+```
+
+> Extras are optional — plain `sentry-sdk` works for all frameworks.
+> Extras install complementary packages.
+
+### Quick Start — Recommended Init
+
+Full init enabling the most features with sensible defaults.
+Place **before** any app/framework code:
+
+```python
+import os
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn=os.environ["SENTRY_DSN"],
+    environment=os.environ.get("SENTRY_ENVIRONMENT", "production"),
+    release=os.environ.get("SENTRY_RELEASE"),   # e.g. "myapp@1.0.0"
+    send_default_pii=True,
+
+    # Tracing (lower to 0.1–0.2 in high-traffic production)
+    traces_sample_rate=1.0,
+
+    # Profiling — continuous, tied to active spans
+    profile_session_sample_rate=1.0,
+    profile_lifecycle="trace",
+
+    # Structured logs (SDK ≥ 2.35.0)
+    enable_logs=True,
+)
+```
+
+### Where to Initialize Per Framework
+
+| Framework     | Where to call `sentry_sdk.init()`                                | Notes                                                               |
+| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Django**    | Top of `settings.py`, before other application imports           | No middleware needed — Sentry patches Django internally             |
+| **Flask**     | Before `app = Flask(__name__)`                                   | Must precede app creation                                           |
+| **FastAPI**   | Before `app = FastAPI()`                                         | `StarletteIntegration` + `FastApiIntegration` auto-enabled together |
+| **Starlette** | Before `app = Starlette(...)`                                    | Same auto-integration as FastAPI                                    |
+| **AIOHTTP**   | Module level, before `web.Application()`                         |                                                                     |
+| **Tornado**   | Module level, before app setup                                   | No integration class needed                                         |
+| **Quart**     | Before `app = Quart(__name__)`                                   |                                                                     |
+| **Falcon**    | Module level, before `app = falcon.App()`                        |                                                                     |
+| **Pyramid**   | Module level, before `config = Configurator()`                   | WSGI framework                                                      |
+| **Sanic**     | Inside `@app.listener("before_server_start")`                    | Sanic’s lifecycle requires async init                               |
+| **Celery**    | `@signals.celeryd_init.connect` in worker AND in calling process | Dual-process init required                                          |
+| **RQ**        | `mysettings.py` loaded by worker via `rq worker -c mysettings`   |                                                                     |
+| **ARQ**       | Both worker module and enqueuing process                         |                                                                     |
+
+**Django example** (`settings.py`):
+
+```python
+import os
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn=os.environ["SENTRY_DSN"],
+    send_default_pii=True,
+    traces_sample_rate=1.0,
+    profile_session_sample_rate=1.0,
+    profile_lifecycle="trace",
+    enable_logs=True,
+)
+
+# rest of Django settings...
+INSTALLED_APPS = [...]
+```
+
+**FastAPI example** (`main.py`):
+
+```python
+import os
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn=os.environ["SENTRY_DSN"],
+    send_default_pii=True,
+    traces_sample_rate=1.0,
+    profile_session_sample_rate=1.0,
+    profile_lifecycle="trace",
+    enable_logs=True,
+)
+
+from fastapi import FastAPI
+app = FastAPI()
+```
+
+### Auto-Enabled vs Explicit Integrations
+
+Most integrations activate automatically when their package is installed — no
+`integrations=[...]` needed:
+
+| Auto-enabled                                                                               | Explicit required                                   |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| Django, Flask, FastAPI, Starlette, AIOHTTP, Tornado, Quart, Falcon, Pyramid, Sanic, Bottle | `DramatiqIntegration`                               |
+| Celery, RQ, Huey, ARQ                                                                      | `GRPCIntegration`                                   |
+| SQLAlchemy, Redis, asyncpg, pymongo                                                        | `StrawberryIntegration`                             |
+| Requests, HTTPX, httpx2, aiohttp-client                                                    | `AsyncioIntegration`                                |
+| OpenAI, Anthropic, LangChain, Pydantic AI, MCP                                             | `OpenAIIntegration` / `AnthropicIntegration` / etc. |
+| Python `logging`, Loguru                                                                   | —                                                   |
+
+### For Each Agreed Feature
+
+Walk through features one at a time.
+Load the reference, follow its steps, verify before moving on:
+
+| Feature          | Reference file          | Load when …                         |
+| ---------------- | ----------------------- | ----------------------------------- |
+| Error Monitoring | `./error-monitoring.md` | Always (baseline)                   |
+| Tracing          | `./tracing.md`          | HTTP handlers / distributed tracing |
+| Profiling        | `./profiling.md`        | Performance-sensitive production    |
+| Logging          | `./logging.md`          | Always; enhanced for Loguru         |
+| Metrics          | `./metrics.md`          | Business KPIs / SLO tracking        |
+| Crons            | `./crons.md`            | Scheduler / cron patterns detected  |
+| AI Monitoring    | `./ai-monitoring.md`    | AI library detected                 |
+
+For each feature: `Read ./<feature>.md`, follow steps exactly, verify it works.
+
+---
+
+## Configuration Reference
+
+### Key `sentry_sdk.init()` Options
+
+| Option                        | Type       | Default        | Purpose                                                                  |
+| ----------------------------- | ---------- | -------------- | ------------------------------------------------------------------------ |
+| `dsn`                         | `str`      | `None`         | SDK disabled if empty; env: `SENTRY_DSN`                                 |
+| `environment`                 | `str`      | `"production"` | e.g., `"staging"`; env: `SENTRY_ENVIRONMENT`                             |
+| `release`                     | `str`      | `None`         | e.g., `"myapp@1.0.0"`; env: `SENTRY_RELEASE`                             |
+| `send_default_pii`            | `bool`     | `False`        | Include IP, headers, cookies, auth user, query strings (ASGI frameworks) |
+| `traces_sample_rate`          | `float`    | `None`         | Transaction sample rate; `None` disables tracing                         |
+| `traces_sampler`              | `Callable` | `None`         | Custom per-transaction sampling (overrides rate)                         |
+| `profile_session_sample_rate` | `float`    | `None`         | Continuous profiling session rate                                        |
+| `profile_lifecycle`           | `str`      | `"manual"`     | `"trace"` = auto-start profiler with spans                               |
+| `profiles_sample_rate`        | `float`    | `None`         | Transaction-based profiling rate                                         |
+| `enable_logs`                 | `bool`     | `False`        | Send logs to Sentry (SDK ≥ 2.35.0)                                       |
+| `sample_rate`                 | `float`    | `1.0`          | Error event sample rate                                                  |
+| `attach_stacktrace`           | `bool`     | `False`        | Stack traces on `capture_message()`                                      |
+| `max_breadcrumbs`             | `int`      | `100`          | Max breadcrumbs per event                                                |
+| `debug`                       | `bool`     | `False`        | Verbose SDK debug output                                                 |
+| `before_send`                 | `Callable` | `None`         | Hook to mutate/drop error events                                         |
+| `before_send_transaction`     | `Callable` | `None`         | Hook to mutate/drop transaction events                                   |
+| `ignore_errors`               | `list`     | `[]`           | Exception types or regex patterns to suppress                            |
+| `auto_enabling_integrations`  | `bool`     | `True`         | Set `False` to disable all auto-detection                                |
+
+#### `OTLPIntegration` Options (pass to constructor)
+
+| Option                       | Type   | Default | Purpose                                                                                                                                                    |
+| ---------------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `setup_otlp_traces_exporter` | `bool` | `True`  | Auto-configure OTLP exporter; set `False` if you send to your own Collector                                                                                |
+| `collector_url`              | `str`  | `None`  | OTLP HTTP endpoint of an OTel Collector (e.g., `http://localhost:4318/v1/traces`); when set, spans are sent to the collector instead of directly to Sentry |
+| `setup_propagator`           | `bool` | `True`  | Auto-configure Sentry propagator for distributed tracing                                                                                                   |
+| `capture_exceptions`         | `bool` | `False` | Intercept exceptions recorded via OTel `Span.record_exception`                                                                                             |
+
+### Environment Variables
+
+| Variable             | Maps to       | Notes                                                             |
+| -------------------- | ------------- | ----------------------------------------------------------------- |
+| `SENTRY_DSN`         | `dsn`         |                                                                   |
+| `SENTRY_RELEASE`     | `release`     | Also auto-detected from git SHA, Heroku, CircleCI, CodeBuild, GAE |
+| `SENTRY_ENVIRONMENT` | `environment` |                                                                   |
+| `SENTRY_DEBUG`       | `debug`       |                                                                   |
+
+---
+
+## Verification
+
+Test that Sentry is receiving events:
+
+```python
+# Trigger a real error event — check dashboard within seconds
+division_by_zero = 1 / 0
+```
+
+Or for a non-crashing check:
+
+```python
+sentry_sdk.capture_message("Sentry Python SDK test")
+```
+
+If nothing appears:
+
+1. Set `debug=True` in `sentry_sdk.init()` — prints SDK internals to stdout
+2. Verify the DSN is correct
+3. Check `SENTRY_DSN` env var is set in the running process
+4. For Celery/RQ: ensure init runs in the **worker** process, not just the calling
+   process
+
+---
+
+## Phase 4: Cross-Link
+
+After completing Python setup, check for a companion frontend missing Sentry:
+
+```bash
+ls frontend/ web/ client/ ui/ 2>/dev/null
+cat frontend/package.json web/package.json client/package.json 2>/dev/null \
+  | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"'
+```
+
+If a frontend exists without Sentry, suggest the matching skill:
+
+| Frontend detected  | Suggest skill                                                                                                                      |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| React / Next.js    | [`react`](../react/index.md)                                                                                                       |
+| Svelte / SvelteKit | [`svelte`](../svelte/index.md)                                                                                                     |
+| Vue / Nuxt         | Use `@sentry/vue` — see [docs.sentry.io/platforms/javascript/guides/vue/](https://docs.sentry.io/platforms/javascript/guides/vue/) |
+| Other JS/TS        | [`react`](../react/index.md) (covers generic browser JS patterns)                                                                  |
+
+---
+
+## Troubleshooting
+
+| Issue                              | Solution                                                                                                                                                                                                    |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Events not appearing               | Set `debug=True`, verify DSN, check env vars in the running process                                                                                                                                         |
+| Malformed DSN error                | Format: `https://<key>@o<org>.ingest.sentry.io/<project>`                                                                                                                                                   |
+| Django exceptions not captured     | Ensure `sentry_sdk.init()` is at the **top** of `settings.py` before other imports                                                                                                                          |
+| Flask exceptions not captured      | Init must happen **before** `app = Flask(__name__)`                                                                                                                                                         |
+| FastAPI exceptions not captured    | Init before `app = FastAPI()`; both `StarletteIntegration` and `FastApiIntegration` auto-enabled                                                                                                            |
+| ASGI chained exceptions suppressed | By default, Sentry’s ASGI middleware strips exception chains (`raise exc from None`). To preserve chained exceptions, set `_experiments={"suppress_asgi_chained_exceptions": False}` in `sentry_sdk.init()` |
+| Celery task errors not captured    | Must call `sentry_sdk.init()` in the **worker process** via `celeryd_init` signal                                                                                                                           |
+| Sanic init not working             | Init must be inside `@app.listener("before_server_start")`, not module level                                                                                                                                |
+| uWSGI not capturing                | Add `--enable-threads --py-call-uwsgi-fork-hooks` to uWSGI command                                                                                                                                          |
+| No traces appearing (native)       | Verify `traces_sample_rate` is set (not `None`); check that the integration is auto-enabled                                                                                                                 |
+| No traces appearing (OTLP)         | Verify `sentry-sdk[opentelemetry-otlp]` is installed; do **not** set `traces_sample_rate` when using `OTLPIntegration`                                                                                      |
+| Profiling not starting             | Requires `traces_sample_rate > 0` + either `profile_session_sample_rate` or `profiles_sample_rate`; **not compatible with OTLP path**                                                                       |
+| `enable_logs` not working          | Requires SDK ≥ 2.35.0; for direct structured logs use `sentry_sdk.logger`; for stdlib bridging use `LoggingIntegration(sentry_logs_level=...)`                                                              |
+| Too many transactions              | Lower `traces_sample_rate` or use `traces_sampler` to drop health checks                                                                                                                                    |
+| Cross-request data leaking         | Don’t use `get_global_scope()` for per-request data — use `get_isolation_scope()`                                                                                                                           |
+| Query strings not captured (ASGI)  | Query strings and client IP in ASGI frameworks (FastAPI, Starlette, etc.) require `send_default_pii=True`                                                                                                   |
+| RQ worker not reporting            | Pass `--sentry-dsn=""` to disable RQ’s own Sentry shortcut; init via settings file instead                                                                                                                  |