Skip to content

Sentry Integration

DocuElevate ships with first-class support for Sentry — an open-source observability platform that provides real-time error tracking and performance monitoring.

When a Sentry DSN is configured, every unhandled exception in the FastAPI web process and Celery worker is automatically captured and sent to your Sentry project. The Sentry Browser SDK is also injected into every rendered page, capturing client-side JavaScript errors, browser performance transactions, and (optionally) session replays. Together these give you full-stack, end-to-end visibility into your deployment.

Quick Start

  1. Create a Sentry project at https://sentry.io (or your self-hosted Sentry instance). Choose the Python platform (the same project and DSN are used for both the server and browser SDKs).
  2. Copy the DSN from Project → Settings → Client Keys (DSN). It looks like: https://<public_key>@o<org_id>.ingest.sentry.io/<project_id>
  3. Set the DSN in your environment or via the Settings → Observability section of the DocuElevate admin UI: bash SENTRY_DSN=https://<public_key>@o<org_id>.ingest.sentry.io/<project_id>
  4. Restart DocuElevate. Sentry initialises automatically on startup — you will see a log line confirming activation. The Sentry Browser SDK <script> tag is automatically injected into every rendered page.

Environment Variables

Server-side (Python SDK)

Variable Default Description
SENTRY_DSN (empty) Sentry DSN URL. Required to enable Sentry. Leave unset to disable.
SENTRY_ENVIRONMENT production Environment label shown in the Sentry dashboard (development, staging, production, …).
SENTRY_TRACES_SAMPLE_RATE 0.1 Fraction of requests captured for performance tracing (0.0 – 1.0). 0.0 disables tracing entirely.
SENTRY_PROFILES_SAMPLE_RATE 0.0 Fraction of profiled transactions sent to Sentry (0.0 – 1.0). Only active when traces > 0.
SENTRY_SEND_DEFAULT_PII false Attach PII (IP addresses, user agents) to events. Disable for GDPR / CCPA compliance.

Browser SDK (JavaScript)

The Sentry Browser SDK is loaded automatically on every rendered page when SENTRY_DSN is set. The DSN is a public key in Sentry's security model and is intentionally embedded in client-side code.

Variable Default Description
SENTRY_JS_TRACES_SAMPLE_RATE 0.0 Fraction of browser page-loads captured for client-side performance tracing (0.0 – 1.0).
SENTRY_JS_REPLAY_SESSION_SAMPLE_RATE 0.0 Fraction of sessions recorded by Sentry Session Replay (0.0 – 1.0).
SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE 0.1 Fraction of error sessions captured with session replay context (0.0 – 1.0).

All variables can alternatively be managed through the Settings → Observability section of the DocuElevate admin UI. Settings stored in the database are applied before Sentry initialises on every startup, so changes made via the UI take effect after a restart without requiring any changes to environment variables or .env files.

Environment-Specific Configuration

Development

SENTRY_DSN=https://<key>@o<org>.ingest.sentry.io/<project>
SENTRY_ENVIRONMENT=development
SENTRY_TRACES_SAMPLE_RATE=1.0            # Capture every request during development
SENTRY_PROFILES_SAMPLE_RATE=1.0
SENTRY_SEND_DEFAULT_PII=true             # OK in dev; disable in production

SENTRY_JS_TRACES_SAMPLE_RATE=1.0         # Capture every browser navigation
SENTRY_JS_REPLAY_SESSION_SAMPLE_RATE=1.0 # Record every session
SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE=1.0

Staging

SENTRY_DSN=https://<key>@o<org>.ingest.sentry.io/<project>
SENTRY_ENVIRONMENT=staging
SENTRY_TRACES_SAMPLE_RATE=0.5
SENTRY_PROFILES_SAMPLE_RATE=0.0
SENTRY_SEND_DEFAULT_PII=false

SENTRY_JS_TRACES_SAMPLE_RATE=0.5
SENTRY_JS_REPLAY_SESSION_SAMPLE_RATE=0.1
SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE=1.0

Production

SENTRY_DSN=https://<key>@o<org>.ingest.sentry.io/<project>
SENTRY_ENVIRONMENT=production
SENTRY_TRACES_SAMPLE_RATE=0.1            # 10 % sampling keeps quota low
SENTRY_PROFILES_SAMPLE_RATE=0.0
SENTRY_SEND_DEFAULT_PII=false            # Default — required for GDPR compliance

SENTRY_JS_TRACES_SAMPLE_RATE=0.1
SENTRY_JS_REPLAY_SESSION_SAMPLE_RATE=0.0 # Disabled; rely on error-triggered replay
SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE=0.1

Docker Compose

Add the variables to your docker-compose.yaml service definitions or to a separate .env file that Docker Compose reads automatically:

services:
  api:
    environment:
      SENTRY_DSN: "https://<key>@o<org>.ingest.sentry.io/<project>"
      SENTRY_ENVIRONMENT: "production"
      SENTRY_TRACES_SAMPLE_RATE: "0.1"
      SENTRY_JS_TRACES_SAMPLE_RATE: "0.1"
      SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE: "0.1"

  worker:
    environment:
      SENTRY_DSN: "https://<key>@o<org>.ingest.sentry.io/<project>"
      SENTRY_ENVIRONMENT: "production"
      SENTRY_TRACES_SAMPLE_RATE: "0.1"

The worker service only needs server-side variables — the Browser SDK runs in the user's browser and is configured via the api service.

Kubernetes

Store the DSN as a Kubernetes Secret:

kubectl create secret generic docuelevate-sentry \
  --from-literal=SENTRY_DSN="https://<key>@o<org>.ingest.sentry.io/<project>"

Then reference it in your Deployment manifest:

envFrom:
  - secretRef:
      name: docuelevate-sentry
env:
  - name: SENTRY_ENVIRONMENT
    value: production
  - name: SENTRY_TRACES_SAMPLE_RATE
    value: "0.1"
  - name: SENTRY_JS_TRACES_SAMPLE_RATE
    value: "0.1"
  - name: SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE
    value: "0.1"

What Is Monitored

FastAPI (web server)

  • Unhandled exceptions — every 5xx error is automatically captured with the full stack trace and request context.
  • Performance transactions — each HTTP request becomes a Sentry transaction, showing time spent in route handlers, middleware, and database calls.
  • Database queries — individual SQL queries are recorded as child spans via the SqlalchemyIntegration.

Celery (background worker)

  • Task failures — any exception raised inside a Celery task is captured, including the task name, ID, and arguments.
  • Task performance — each task execution is a Sentry transaction, letting you identify slow or failing pipelines.
  • Beat task monitoring — the CeleryIntegration(monitor_beat_tasks=True) option tracks whether scheduled tasks run on time (requires Sentry Crons).

Logging integration

Log messages at ERROR level and above are automatically forwarded to Sentry as events. Messages at INFO level are recorded as breadcrumbs (contextual trail leading up to an error).

Browser (JavaScript SDK)

  • Client-side errors — unhandled JavaScript exceptions and Promise rejections are captured automatically with browser context (URL, user agent, breadcrumbs).
  • Browser performance — page load, navigation, and resource timing data is captured as Sentry transactions when SENTRY_JS_TRACES_SAMPLE_RATE > 0.
  • Session Replay — screen recordings of user sessions (or just sessions containing errors) can be captured when the relevant replay sample rates are set above 0.0. Replay data helps reproduce and diagnose hard-to-find UI bugs.

Disabling Sentry

Simply leave SENTRY_DSN unset (or set it to an empty string). Neither the Python SDK nor the Browser SDK <script> tag is loaded, and no data is sent.

SDK Version

  • Server: DocuElevate uses sentry-sdk >=2.20.0,<3.0.0 with the fastapi, celery, and sqlalchemy extras.
  • Browser: The bundle.tracing.replay.min.js bundle from the Sentry Browser SDK v10 is loaded from the official Sentry CDN (browser.sentry-cdn.com). The version pin is in frontend/templates/base.html.

Troubleshooting

No events appear in Sentry

  1. Verify the DSN is correct and the Sentry project is active.
  2. Check the application logs for the Sentry initialised message at startup. If it is absent, the DSN is not being read — confirm the environment variable name is SENTRY_DSN, or check the Settings → Observability section of the admin UI if you configured it there.
  3. Test with SENTRY_TRACES_SAMPLE_RATE=1.0 so that every request is sent.

No browser errors in Sentry

  1. Confirm SENTRY_DSN is set — the Browser SDK <script> tag is only injected when the DSN is non-empty.
  2. Open browser DevTools → Network and verify that the Sentry CDN bundle (bundle.tracing.replay.min.js) loads successfully (HTTP 200).
  3. Open DevTools → Console and run window.Sentry — it should be an object if the SDK loaded correctly.
  4. Check that SENTRY_JS_TRACES_SAMPLE_RATE and replay rates are set to values > 0 if you expect performance / replay data (they default to 0.0).

sentry-sdk import error

sentry-sdk is not installed.

Run pip install 'sentry-sdk[fastapi,celery,sqlalchemy]' inside your container, or rebuild the Docker image.

PII / GDPR concerns

By default SENTRY_SEND_DEFAULT_PII=false, which prevents IP addresses and user agents from being attached to server-side events. Session Replay data may capture user interactions — review Sentry's privacy documentation and your organisation's privacy policy before enabling replay.

High Sentry quota usage

  • Lower SENTRY_TRACES_SAMPLE_RATE (e.g. 0.05 for 5 %) or set it to 0.0 to disable server-side performance tracing.
  • Set SENTRY_JS_TRACES_SAMPLE_RATE=0.0 to disable browser performance tracing.
  • Set SENTRY_JS_REPLAY_SESSION_SAMPLE_RATE=0.0 and SENTRY_JS_REPLAY_ON_ERROR_SAMPLE_RATE=0.0 to disable Session Replay entirely.

Best Practices

  • Use separate Sentry projects (or at least separate environments) for development, staging, and production so that noise from non-production environments does not pollute your production alerts.
  • Configure alert rules in Sentry to notify your team (via email, Slack, PagerDuty, etc.) when error rates spike.
  • Use release tracking: DocuElevate automatically sets release to the current VERSION string, enabling you to correlate errors with specific releases.
  • Set up performance baselines using Sentry's Performance dashboard so that you can detect regressions after deployments.
  • Review the Sentry Python documentation for advanced configuration options such as custom tags, user context, and scrubbing sensitive data.
  • Review the Sentry Browser SDK documentation for advanced browser SDK configuration.