Sentry — Browser SDK

1. Pick where the DSN comes from

There are two ways to point the browser SDK at a Sentry project. Use one:

(a) Recommended — separate browser DSN via the Settings UI. Sentry’s own guidance is one project per platform: a Python project for backend errors and a JavaScript-Browser project for client-side errors. Set the dedicated browser DSN under Settings → General Settings → Sentry Browser Monitoring → Connection:

No Odoo restart required — changes take effect on the next page load.

(b) Fallback — shared DSN via ``odoo.conf``. If the Connection fields above are left blank, the controller reads the same top-level sentry_* options the OCA server-side sentry module uses on the 18.0 series (the dedicated [sentry] section only exists from 19.0):

[options]
sentry_dsn = https://<public_key>@sentry.example.com/<project_id>
sentry_release = 1.3.2
sentry_environment = production

This path is convenient for single-project deployments that want both backend Python events and browser JavaScript events going to the same Sentry project. Editing odoo.conf requires an Odoo restart. A legacy DSN with a secret (https://key:secret@…) is served to the browser without the secret part.

The UI value always wins when both are set. Whichever source the DSN comes from, the controller strips a legacy :<secret> component before serving it — the browser only ever needs the public key — and the Settings form refuses a Browser DSN that carries one.

2. Settings → General Settings → Sentry Browser Monitoring

Each tier is independently toggleable:

3. User preferences → Privacy — per-user session-replay opt-out

Each user can disable session replay for their own sessions, regardless of the database-wide Tier 2 setting. The browser SDK still loads (the bundle URL doesn’t change), but the Replay integration is never registered for the opted-out user — no DOM observer, no recording.

To enable: open the user’s profile (top-right avatar → My Profile → Preferences → Privacy) and check Disable Sentry session replay.

The toggle is self-writeable: users can manage it without administrator help.

What leaves the server per user: events carry the numeric user id plus the app categories of the user’s groups (e.g. Sales,Accounting) as the odoo.category tag, cut to Sentry’s 200-character tag limit. No group names, email or display name are sent; replay masking covers all text, inputs and media by default.

4. Backend errors and OWL component context

In the backend (/odoo/*) Odoo’s error service already catches every window error and unhandled rejection, so the module registers one error_handlers entry and turns the SDK’s own global handlers and callback wrappers (GlobalHandlers, BrowserApiErrors) off there. Each crash is reported once, and OWL component crashes carry two extra fields:

• tags.owl = true
• extra.component_tree — the OWL component path of the failing render

Server-side and transport errors (RPCError, including session expiry, ConnectionLostError, ConnectionAbortedError, RequestEntityTooLargeError) are not reported from the browser — the OCA sentry module already reports the server-side ones — they only leave an odoo.rpc breadcrumb on the next browser event. When Tier 2 replay is on, a server error still uploads the buffered replay, so the server-side event has a recording to link to through the trace propagated on the request. Odoo’s standard “Oops!” dialog still shows as before. No configuration needed. Portal and website pages have no error service, so the SDK’s global handlers stay on there.

Browser profiling — extra setup

The JS Self-Profiling API requires the browser to receive a permission header on the document HTML response:

Document-Policy: js-profiling

Odoo’s default web responses do not emit this header. You’ll need to add it at your reverse proxy. nginx example:

location /odoo {
    proxy_pass http://odoo:8069;
    add_header Document-Policy "js-profiling";
}

Without the header, the Profiling integration registers cleanly and sends profile payloads, but they will be empty — no client-side error, just no useful data in Sentry’s Profiling tab.

Vendored Sentry SDK

The browser SDK ships vendored inside the module under sentry_client/static/lib/sentry/<version>/. The default Sentry SDK source URL points at this in-module path, so the browser loads the SDK from the same origin as Odoo — no traffic to browser.sentry-cdn.com, no air-gap workarounds needed.

To bump the vendored version, run the refresh script:

cd sentry_client/
./scripts/refresh-vendor-bundle.sh 10.55.0   # whatever you want
git add static/lib/sentry/10.55.0/
git commit -m "[IMP] sentry_client: bump vendored SDK to 10.55.0"

The script downloads each bundle from browser.sentry-cdn.com, verifies it against Sentry’s published SHA-384 SRI hash, drops the LICENSE file, and writes a SHA256SUMS for reviewers. After committing, update the Sentry SDK version in Settings → General Settings → Sentry Browser Monitoring to match.

To revert to the public CDN at runtime (e.g. for quick A/B testing), override Sentry SDK source URL to https://browser.sentry-cdn.com in the Settings page.

Sentry server compatibility

The browser SDK talks to whatever Sentry instance you point the DSN at — either sentry.io or a self-hosted instance. Feature support depends on the Sentry server version:

For sentry.io: all features are always available.

For self-hosted: check your tag at /opt/sentry/install/_version.sh (or docker exec <sentry-web> sentry --version). If a feature you’ve enabled isn’t supported by your Sentry server, the browser SDK still sends the envelope but the server discards it — no client-side error.

Per-user opt-out

Top-right avatar → My Profile → Preferences → Privacy → Disable Sentry session replay. Saves to your own user record. The opt-out only suppresses session replay; basic error capture (Tier 0) still fires.

OWL component context

When the backend OWL stack raises an exception (the usual “Oops!” dialog you see in the Odoo web client), the resulting Sentry event automatically carries:

• tags.owl = true
• extra.component_tree — the OWL component path

No configuration needed — the OCA sentry_client module registers an entry in @web/core/error_handlers at install time. Standard Odoo error UX is unaffected.

Authors

• Ledoent

Contributors

• Don Kendall <dkendall@ledoweb.com>

Other credits

The development of this module is led by Ledoent.

Companion to the OCA `sentry <../sentry>`__ module for server-side error capture.

Maintainers

This module is maintained by the OCA.

OCA, or the Odoo Community Association, is a nonprofit organization whose mission is to support the collaborative development of Odoo features and promote its widespread use.

Current maintainer:

This module is part of the OCA/server-tools project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.