Sentry — Browser SDK

• Elegir de dónde proviene el DSN

Hay dos formas de apuntar el SDK del navegador a un proyecto de Sentry. Use una:

(a) Recomendado — DSN de navegador separado a través de la interfaz de Ajustes. La propia guía de Sentry es un proyecto por plataforma: un proyecto Python para errores de backend y un proyecto JavaScript-Browser para errores del lado del cliente. Configure el DSN de navegador dedicado en Ajustes → Ajustes generales → Sentry Browser Monitoring → Conexión:

| Campo | Ejemplo | Notas | |---|---|---| | Browser DSN | https://<public_key>@sentry.example.com/<project_id> | DSN público del proyecto JavaScript. Seguro para incrustar en código de cliente según la documentación de Sentry. | | Environment | production-web | Etiqueta cada evento del navegador. Puede diferir de la etiqueta de entorno del backend. | | Release | hash del asset-bundle o SHA del despliegue | Etiqueta cada evento del navegador. Puede diferir de la release de Odoo Python. |

No se requiere reiniciar Odoo — los cambios surten efecto en la siguiente carga de página.

(b) Alternativa — DSN compartido a través de odoo.conf. Si los campos de Conexión anteriores se dejan en blanco, el controlador lee las mismas opciones de nivel superior sentry_* que usa el módulo sentry del lado del servidor de OCA en la serie 18.0 (la sección dedicada [sentry] solo existe a partir de 19.0):

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

Esta ruta es conveniente para despliegues de un solo proyecto que quieren que tanto los eventos Python del backend como los eventos JavaScript del navegador vayan al mismo proyecto de Sentry. Editar odoo.conf requiere reiniciar Odoo. Un DSN heredado con un secreto (https://key:secret@…) se sirve al navegador sin la parte del secreto.

El valor de la interfaz siempre prevalece cuando ambos están configurados. Independientemente de la fuente de la que provenga el DSN, el controlador elimina un componente heredado :<secret> antes de servirlo — el navegador solo necesita la clave pública — y el formulario de Ajustes rechaza un Browser DSN que lo lleve.

• Ajustes → Ajustes generales → Sentry Browser Monitoring

Cada nivel se puede activar de forma independiente:

Nivel 0 — Capturar errores del navegador (predeterminado recomendado una vez configurado un DSN)

Carga bundle.min.js (~30KB gzip). Conecta window.onerror y window.onunhandledrejection. Envía eventos con el id + email del usuario conectado como Sentry.setUser(...).

Nivel 1 — Monitorización de rendimiento

Habilita BrowserTracing. Instrumenta automáticamente fetch / XHR, navigation timing y long-task observer. Añade aproximadamente un 5–10% de sobrecarga por petición con una tasa de muestreo de 1.0 más ancho de banda adicional por petición trazada. Recomendado en producción: 0.05 o inferior.

Nivel 2 — Session replay

Habilita @sentry/replay. Añade ~100KB a cada página y graba mutaciones del DOM + consola + actividad de red. Se recomienda encarecidamente Healthy-session sample = 0.0 y On-error sample = 1.0 para que la grabación solo se active en sesiones que ya hayan sufrido un error.

Nivel 3 — Extras opcionales

• Widget de comentarios del usuario — añade un botón de comentarios.
• Perfilado de CPU del navegador — captura muestras de JS Self-Profiling para transacciones trazadas. Tiene su propio control deslizante de tasa de muestreo. Requiere que la página se sirva con una cabecera HTTP Document-Policy: js-profiling. Consulte "Perfilado del navegador — configuración adicional" más abajo.
• Captura de logs de consola — sube llamadas console.log / console.warn como entradas de Sentry Log. Ruidoso sin filtrado.
• Preferencias del usuario → Privacidad — exclusión del session-replay por usuario

Cada usuario puede desactivar el session replay para sus propias sesiones, independientemente del ajuste de Nivel 2 a nivel de base de datos. El SDK del navegador sigue cargándose (la URL del bundle no cambia), pero la integración Replay nunca se registra para el usuario que ha optado por excluirse — sin observador del DOM, sin grabación.

Para habilitarlo: abra el perfil del usuario (avatar arriba a la derecha → Mi perfil → Preferencias → Privacidad) y marque Disable Sentry session replay.

El interruptor es autoeditable: los usuarios pueden gestionarlo sin ayuda de un administrador.

Qué sale del servidor por usuario: los eventos llevan el id numérico del usuario más las categorías de aplicación de los grupos del usuario (p. ej. Sales,Accounting) como la etiqueta odoo.category, recortada al límite de 200 caracteres de etiqueta de Sentry. No se envían nombres de grupo, email ni nombre para mostrar; el enmascaramiento del replay cubre todo el texto, las entradas y los medios por defecto.

• Errores de backend y contexto de componentes OWL

En el backend (/odoo/*) el servicio de errores de Odoo ya captura cada error de ventana y cada rechazo no gestionado, por lo que el módulo registra una entrada error_handlers y desactiva allí los propios manejadores globales y envoltorios de callback del SDK (GlobalHandlers, BrowserApiErrors). Cada fallo se reporta una vez, y los fallos de componentes OWL llevan dos campos extra:

• tags.owl = true
• extra.component_tree — la ruta del componente OWL del render que falla

Los errores del lado del servidor y de transporte (RPCError, incluida la expiración de sesión, ConnectionLostError, ConnectionAbortedError, RequestEntityTooLargeError) no se reportan desde el navegador — el módulo sentry de OCA ya reporta los del lado del servidor — solo dejan una miga de pan odoo.rpc en el siguiente evento del navegador. Cuando el replay de Nivel 2 está activado, un error del servidor igualmente sube el replay en búfer, de modo que el evento del lado del servidor tiene una grabación a la que enlazar a través del trace propagado en la petición. El diálogo estándar "¡Vaya!" de Odoo sigue mostrándose como antes. No se necesita configuración. Las páginas de portal y sitio web no tienen servicio de errores, por lo que los manejadores globales del SDK permanecen activados allí.

Perfilado del navegador — configuración adicional

La API JS Self-Profiling requiere que el navegador reciba una cabecera de permiso en la respuesta HTML del documento:

Document-Policy: js-profiling

Las respuestas web predeterminadas de Odoo no emiten esta cabecera. Tendrá que añadirla en su proxy inverso. Ejemplo con nginx:

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

Sin la cabecera, la integración Profiling se registra correctamente y envía cargas de perfil, pero estarán vacías — sin error del lado del cliente, simplemente sin datos útiles en la pestaña Profiling de Sentry.

SDK de Sentry vendorizado

El SDK del navegador se distribuye vendorizado dentro del módulo en sentry_client/static/lib/sentry/<version>/. La URL de origen predeterminada del SDK de Sentry apunta a esta ruta dentro del módulo, por lo que el navegador carga el SDK desde el mismo origen que Odoo — sin tráfico a browser.sentry-cdn.com, sin necesidad de soluciones para redes aisladas.

Para actualizar la versión vendorizada, ejecute el script de actualización:

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"

El script descarga cada bundle desde browser.sentry-cdn.com, lo verifica contra el hash SRI SHA-384 publicado por Sentry, elimina el archivo LICENSE y escribe un SHA256SUMS para los revisores. Tras hacer commit, actualice la versión del SDK de Sentry en Ajustes → Ajustes generales → Sentry Browser Monitoring para que coincida.

Para volver al CDN público en tiempo de ejecución (p. ej. para pruebas A/B rápidas), sobrescriba Sentry SDK source URL a https://browser.sentry-cdn.com en la página de Ajustes.

Compatibilidad con el servidor de Sentry

El SDK del navegador se comunica con cualquier instancia de Sentry a la que apunte el DSN — ya sea sentry.io o una instancia autoalojada. La compatibilidad de características depende de la versión del servidor de Sentry:

| Característica | Servidor de Sentry mínimo | Notas | |---|---|---| | Nivel 0 — captura de errores | v9.0+ | Ingesta básica de eventos, compatible con cualquier Sentry moderno. | | Nivel 1 — rendimiento / tracing | v10.0+ | La interfaz de tracing se lanzó en Sentry 10. | | Nivel 2 — session replay | v22.10.0+ (oct 2022) + feature flag | La ingesta de Replay se introdujo en la versión autoalojada 22.10. La característica también debe estar habilitada en el servidor: configure SENTRY_FEATURES["organizations:session-replay"] = True (y …-ui, …-recording-scrubbing) en sentry.conf.py, luego reinicie web + ingest-replay-recordings. Sin el flag, los envelopes del navegador llegan a /api/<n>/envelope/ pero se descartan silenciosamente — sin superficie en la interfaz, sin error. | | Nivel 3 — widget de comentarios | v23.6.0+ (jun 2023) | La API moderna de comentarios programática. Las versiones anteriores siguen funcionando con la ruta heredada Sentry.showReportDialog, que este módulo no usa. | | Nivel 3 — perfilado del navegador | v24.0+ (ene 2024) | Más la cabecera Document-Policy: js-profiling (véase arriba). | | Nivel 3 — captura de logs de consola | v25.0+ (mar 2025) | API de Sentry Logs. Las versiones del servidor anteriores a la v25 ingerirán los eventos como un envelope de log genérico; la interfaz dedicada de Logs requiere v25+. |

Para sentry.io: todas las características están siempre disponibles.

Para autoalojado: compruebe su etiqueta en /opt/sentry/install/_version.sh (o docker exec <sentry-web> sentry --version). Si una característica que ha habilitado no es compatible con su servidor de Sentry, el SDK del navegador igualmente envía el envelope pero el servidor lo descarta — sin error del lado del cliente.

Una vez que Tier 0 está habilitado y se ha configurado un DSN, la siguiente carga de página inyecta el SDK de navegador de Sentry (vendored) y comienza a capturar errores. No se necesita ninguna acción adicional por parte del usuario.

Para verificar la integración:

• Abre la consola de herramientas de desarrollo del navegador en cualquier página de Odoo.
• Ejecuta throw new Error("sentry_client smoke test").
• El error aparece en tu proyecto de Sentry en unos segundos, etiquetado con tu Odoo user.id, release y environment.

Opt-out por usuario

Avatar en la esquina superior derecha → My Profile → Preferences → Privacy → Disable Sentry session replay. Se guarda en tu propio registro de usuario. El opt-out solo suprime la repetición de sesión; la captura básica de errores (Tier 0) sigue activándose.

Contexto de componentes OWL

Cuando el stack OWL del backend lanza una excepción (el habitual diálogo "¡Vaya!" que ves en el cliente web de Odoo), el evento de Sentry resultante incluye automáticamente:

• tags.owl = true
• extra.component_tree — la ruta del componente OWL

No se necesita configuración — el módulo OCA sentry_client registra una entrada en @web/core/error_handlers en el momento de la instalación. La UX de errores estándar de Odoo no se ve afectada.