Raven: Integración con Sentry
Integra Drupal con Sentry, una plataforma de código abierto para monitoreo de aplicaciones y seguimiento de errores.
raven
Install
composer require 'drupal/raven:^7.3'
Overview
El módulo Raven proporciona una integración completa con Sentry, una plataforma de código abierto para monitoreo de aplicaciones y seguimiento de errores. Captura mensajes de registro de Drupal, errores fatales de PHP, errores de JavaScript y excepciones de comandos Drush, proporcionando trazas de pila completas y metadatos personalizables para cada evento.
El módulo soporta el rastreo de rendimiento de Sentry, creando eventos de transacción para cada solicitud/respuesta manejada por Drupal, con tramos para solicitudes de cliente HTTP, consultas de base de datos y plantillas Twig. Permite el rastreo distribuido entre servicios enviando el encabezado HTTP sentry-trace con las solicitudes.
También se soportan los registros estructurados de Sentry, que son registros ligeros sin trazas de pila que solo se envían una vez al final de la solicitud. El módulo se integra con el módulo CSP y el módulo Security Kit para informes de Content Security Policy, y con el módulo Monitoring para cambios en el estado de sensores.
Features
- Captura mensajes de registro de Drupal en niveles de severidad configurables (Emergency, Alert, Critical, Error, Warning, Notice, Info, Debug)
- Maneja errores fatales de PHP como exceder el límite de memoria
- Captura errores de JavaScript mediante el SDK de JavaScript de Sentry con control de permisos de usuario
- Captura excepciones lanzadas por comandos Drush
- Proporciona trazas de pila completas y metadatos personalizables para cada evento
- Rastreo de rendimiento de solicitud/respuesta con tasas de muestreo configurables
- Rastreo de rendimiento de consultas de base de datos con argumentos de consulta opcionales
- Rastreo de rendimiento de plantillas Twig
- Rastreo de rendimiento del navegador con tramos de Interaction to Next Paint (INP)
- Rastreo distribuido entre servicios mediante el encabezado HTTP sentry-trace
- Soporte de registros estructurados de Sentry para registro ligero
- Manejo de informes de Content Security Policy (CSP) mediante integración con el módulo CSP
- Integración con el módulo Security Kit para informes de CSP y Certificate Transparency
- Integración con el módulo Monitoring para cambios en el estado de sensores
- Monitoreo de cron con slug de monitor configurable
- Soporte de perfilado de Sentry (requiere la extensión PHP Excimer)
- Tunelización de solicitudes para evitar bloqueadores de anuncios o alcanzar servidores Sentry no públicos
- Diálogo de retroalimentación del usuario para excepciones de JavaScript
- Soporte de variables de entorno para configuración de DSN, entorno y versión
- Limitación de tasa para eventos de registro por solicitud
- Compresión HTTP para solicitudes a Sentry
- Soporte de integración con el módulo Monolog
Use Cases
Seguimiento de errores para sitios en producción
Configure el DSN de Sentry y habilite los niveles de registro apropiados (típicamente Error, Critical, Alert, Emergency) para capturar todos los errores y excepciones de PHP. Habilite el manejador de errores fatales para capturar errores de límite de memoria excedido y otros errores fatales. Otorgue el permiso 'Send JavaScript errors to Sentry' a los usuarios autenticados para rastrear errores del frontend.
Monitoreo de rendimiento
Habilite el rastreo de rendimiento de solicitud/respuesta y establezca un traces_sample_rate (por ejemplo, 0.1 para el 10% de las solicitudes). Habilite el rastreo de base de datos y el rastreo de Twig para spans detallados. Configure browser_traces_sample_rate para datos de rendimiento del frontend. Use objetivos de propagación de trazas para habilitar el rastreo distribuido entre microservicios.
Desarrollo y depuración
Habilite todos los niveles de registro incluyendo Notice, Info y Debug para un registro completo durante el desarrollo. Use los botones de prueba en la página de administración para verificar la configuración. Ejecute 'drush --debug raven:captureMessage' para ver la salida de depuración detallada del SDK de Sentry.
Monitoreo de cron
Cree un monitor de cron en el panel de Sentry y configure el slug del monitor en la configuración de Raven. El módulo enviará automáticamente eventos de check-in al inicio y al final de las ejecuciones de cron, permitiéndole monitorear la salud del cron y la duración de ejecución.
Evasión de bloqueadores de anuncios con túnel
Habilite el túnel de errores para enrutar las solicitudes de Sentry a través de su sitio web en /raven/tunnel. Esto evita que los bloqueadores de anuncios bloqueen las solicitudes de Sentry y permite el acceso a servidores de Sentry que no son públicamente accesibles.
Recolección de comentarios de usuarios
Habilite 'Show user feedback dialog' para solicitar información adicional a los usuarios cuando ocurran excepciones de JavaScript. Configure la URL de Error embed si usa un servidor Sentry personalizado para asegurar que las reglas CSP estén correctamente configuradas.
Seguimiento de errores consciente de la privacidad
Deje deshabilitados 'Send user data to Sentry' y 'Capture end user IP addresses' para evitar recopilar información de identificación personal. Use ignored_channels para filtrar los registros de 'access denied' y 'page not found'. Implemente un callback before_send personalizado a través del evento OptionsAlter para limpiar datos sensibles.
Tips
- Use variables de entorno (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE) para diferentes entornos de despliegue
- Establezca un traces_sample_rate bajo en producción (por ejemplo, 0.01-0.1) para evitar la recolección excesiva de datos
- Habilite registros estructurados para un registro ligero sin trazas de pila
- Use el evento OptionsAlter para agregar integraciones personalizadas, callbacks o configurar la lista ignore_exceptions
- Agregue contexto personalizado usando Sentry::configureScope() o Sentry::withScope() en su código
- Las dependencias en la biblioteca raven/raven aseguran que el SDK de JavaScript de Sentry se cargue antes de sus scripts personalizados
- Use drush --debug raven:captureMessage para solucionar problemas de comunicación con el SDK
Technical Details
Admin Pages 1
/admin/config/development/logging
El módulo Raven añade su configuración a la página de ajustes de Registro y errores del núcleo. Esta página permite configurar todos los aspectos de la integración con Sentry, incluyendo ajustes de DSN, manejo de errores, rastreo de rendimiento y varias integraciones.
Permissions 3
Hooks 6
hook_page_attachments
Adjunta la biblioteca JavaScript y la configuración de Sentry a las páginas para usuarios con permiso de seguimiento de errores JavaScript.
hook_cron
Implementa el monitoreo de cron enviando eventos de verificación a Sentry cuando se configura un slug de monitor cron.
hook_form_system_logging_settings_alter
Añade elementos de formulario de configuración de Sentry a la página de configuración de Registro y errores del núcleo.
hook_help
Proporciona texto de ayuda para la página de ayuda del módulo en admin/help/raven.
hook_monitoring_run_sensors
Envía los cambios de estado de los sensores del módulo Monitoring a Sentry cuando está habilitado.
hook_requirements
Verifica la extensión cURL, el SDK PHP de Sentry, la extensión Zlib y la extensión Excimer. Reporta el estado de configuración de Sentry en la página de informe de estado.
Drush Commands 2
drush raven:captureMessage
Envía un mensaje de prueba a Sentry. Útil para verificar la configuración de Sentry.
drush raven:captureLog
Envía un elemento de logs estructurado a Sentry. Prueba la funcionalidad de registro estructurado.
Troubleshooting 6
Verifique la página de Informe de estado (admin/reports/status) para el estado de configuración de Sentry y errores. Verifique que el DSN sea correcto. Haga clic en el botón 'Send PHP test message to Sentry' para ver la salida de depuración. Asegúrese de que los niveles de registro apropiados estén habilitados.
Verifique que el usuario tenga el permiso 'Send JavaScript errors to Sentry'. Revise la consola del navegador en busca de errores del SDK de Sentry o códigos de estado HTTP. Asegúrese de que el DSN de JavaScript esté configurado. Verifique si los bloqueadores de anuncios están bloqueando las solicitudes (considere habilitar el túnel).
Configure la opción rate_limit para establecer un límite superior de eventos por solicitud. Use ignored_channels para filtrar canales de registro ruidosos como 'access denied' y 'page not found'. Implemente un callback before_send a través del evento OptionsAlter para filtrar eventos.
Deshabilite 'Reflection tracing in stacktraces', 'Send request body to Sentry' y 'Database performance tracing query arguments'. El módulo sanitiza automáticamente los campos de contraseña. Implemente un callback before_send personalizado para limpieza adicional.
Verifique que el usuario tenga el permiso 'Send performance traces to Sentry'. Compruebe que traces_sample_rate esté establecido a un valor mayor que 0. Asegúrese de que request_tracing esté habilitado. Note que las páginas en caché no se rastrean.
Si usa el módulo CSP, seleccione 'Sentry' como el manejador de informes. Si usa Security Kit, habilite 'Send security header reports to Sentry'. El módulo ajusta automáticamente las directivas CSP cuando está correctamente configurado.
Security Notes 6
- El rastreo de reflexión expone argumentos de funciones en las trazas de pila que pueden contener datos sensibles como contraseñas o tokens
- Enviar el cuerpo de la solicitud a Sentry puede exponer datos de formularios incluyendo contraseñas e información personal
- El rastreo de base de datos con argumentos de consulta puede exponer datos sensibles almacenados en la base de datos
- La configuración de datos de usuario (correo electrónico, nombre de usuario, dirección IP) debe considerarse cuidadosamente para el cumplimiento del GDPR
- El módulo sanitiza automáticamente los campos de contraseña en los datos de solicitud pero los campos sensibles personalizados requieren configuración adicional
- Al usar el túnel, asegure controles de acceso apropiados ya que el endpoint del túnel acepta solicitudes POST de usuarios con permiso de errores de JavaScript