Raven: Sentry Integration
Integrates Drupal with Sentry, an open-source application monitoring and error tracking platform.
raven
Install
composer require 'drupal/raven:^7.3'
Overview
Raven module provides comprehensive integration with Sentry, an open-source application monitoring and error tracking platform. It captures Drupal log messages, fatal PHP errors, JavaScript errors, and Drush command exceptions, providing full stacktraces and customizable metadata for each event.
The module supports Sentry performance tracing, creating transaction events for each request/response handled by Drupal, with spans for HTTP client requests, database queries, and Twig templates. It enables distributed tracing across services by sending the sentry-trace HTTP header with requests.
Sentry structured logs are also supported - these lightweight logs lack stacktraces and are only sent once at the end of the request. The module integrates with CSP module and Security Kit module for Content Security Policy reporting, and with Monitoring module for sensor status changes.
Features
- Captures Drupal log messages at configurable severity levels (Emergency, Alert, Critical, Error, Warning, Notice, Info, Debug)
- Handles fatal PHP errors such as memory limit exceeded
- Captures JavaScript errors via Sentry JavaScript SDK with user permission control
- Catches exceptions thrown by Drush commands
- Provides full stacktraces and customizable metadata for each event
- Request/response performance tracing with configurable sample rates
- Database query performance tracing with optional query arguments
- Twig template performance tracing
- Browser performance tracing with Interaction to Next Paint (INP) spans
- Distributed tracing across services via sentry-trace HTTP header
- Sentry structured logs support for lightweight logging
- Content Security Policy (CSP) report handling via CSP module integration
- Security Kit module integration for CSP and Certificate Transparency reports
- Monitoring module integration for sensor status changes
- Cron monitoring with configurable monitor slug
- Sentry profiling support (requires Excimer PHP extension)
- Request tunneling to bypass ad-blockers or reach non-public Sentry servers
- User feedback dialog for JavaScript exceptions
- Environment variable support for DSN, environment, and release configuration
- Rate limiting for log events per request
- HTTP compression for Sentry requests
- Monolog module integration support
Use Cases
Error tracking for production sites
Configure Sentry DSN and enable appropriate log levels (typically Error, Critical, Alert, Emergency) to capture all PHP errors and exceptions. Enable the fatal error handler to catch memory limit exceeded and other fatal errors. Grant 'Send JavaScript errors to Sentry' permission to authenticated users to track frontend errors.
Performance monitoring
Enable request/response performance tracing and set a traces_sample_rate (e.g., 0.1 for 10% of requests). Enable database tracing and Twig tracing for detailed spans. Configure browser_traces_sample_rate for frontend performance data. Use trace propagation targets to enable distributed tracing across microservices.
Development and debugging
Enable all log levels including Notice, Info, and Debug for comprehensive logging during development. Use the test buttons on the admin page to verify configuration. Run 'drush --debug raven:captureMessage' to see detailed debug output from the Sentry SDK.
Cron monitoring
Create a cron monitor in the Sentry dashboard and configure the monitor slug in Raven settings. The module will automatically send check-in events at the start and end of cron runs, allowing you to monitor cron health and execution duration.
Ad-blocker bypass with tunneling
Enable error tunneling to route Sentry requests through your website at /raven/tunnel. This prevents ad-blockers from blocking Sentry requests and allows access to Sentry servers that are not publicly accessible.
User feedback collection
Enable 'Show user feedback dialog' to prompt users for additional information when JavaScript exceptions occur. Configure the Error embed URL if using a custom Sentry server to ensure CSP rules are correctly set up.
Privacy-conscious error tracking
Leave 'Send user data to Sentry' and 'Capture end user IP addresses' disabled to avoid collecting personally identifiable information. Use ignored_channels to filter out 'access denied' and 'page not found' logs. Implement custom before_send callback via OptionsAlter event to scrub sensitive data.
Tips
- Use environment variables (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE) for different deployment environments
- Set a low traces_sample_rate in production (e.g., 0.01-0.1) to avoid excessive data collection
- Enable structured logs for lightweight logging without stacktraces
- Use the OptionsAlter event to add custom integrations, callbacks, or configure ignore_exceptions list
- Add custom context using Sentry::configureScope() or Sentry::withScope() in your code
- Dependencies on raven/raven library ensure Sentry JavaScript SDK is loaded before your custom scripts
- Use drush --debug raven:captureMessage to troubleshoot SDK communication issues
Technical Details
Admin Pages 1
/admin/config/development/logging
The Raven module adds its configuration to the core Logging and errors settings page. This page allows you to configure all aspects of Sentry integration including DSN settings, error handling, performance tracing, and various integrations.
Permissions 3
Hooks 6
hook_page_attachments
Attaches JavaScript library and Sentry configuration to pages for users with JavaScript error tracking permission.
hook_cron
Implements cron monitoring by sending check-in events to Sentry when a cron monitor slug is configured.
hook_form_system_logging_settings_alter
Adds Sentry configuration form elements to the core Logging and errors settings page.
hook_help
Provides help text for the module's help page at admin/help/raven.
hook_monitoring_run_sensors
Sends Monitoring module sensor status changes to Sentry when enabled.
hook_requirements
Checks for cURL extension, Sentry PHP SDK, Zlib extension, and Excimer extension. Reports Sentry configuration status on the status report page.
Drush Commands 2
drush raven:captureMessage
Send a test message to Sentry. Useful for verifying Sentry configuration.
drush raven:captureLog
Send a structured logs item to Sentry. Tests structured logging functionality.
Troubleshooting 6
Check the Status report page (admin/reports/status) for Sentry configuration status and errors. Verify the DSN is correct. Click 'Send PHP test message to Sentry' button to see debug output. Ensure the appropriate log levels are enabled.
Verify the user has the 'Send JavaScript errors to Sentry' permission. Check the browser console for Sentry SDK errors or HTTP status codes. Ensure the JavaScript DSN is configured. Check if ad-blockers are blocking requests (consider enabling tunneling).
Configure the rate_limit setting to set an upper bound on events per request. Use ignored_channels to filter out noisy log channels like 'access denied' and 'page not found'. Implement a before_send callback via OptionsAlter event to filter events.
Disable 'Reflection tracing in stacktraces', 'Send request body to Sentry', and 'Database performance tracing query arguments'. The module automatically sanitizes password fields. Implement custom before_send callback for additional scrubbing.
Verify the user has 'Send performance traces to Sentry' permission. Check that traces_sample_rate is set to a value greater than 0. Ensure request_tracing is enabled. Note that cached pages are not traced.
If using CSP module, select 'Sentry' as the reporting handler. If using Security Kit, enable 'Send security header reports to Sentry'. The module automatically adjusts CSP directives when properly configured.
Security Notes 6
- Reflection tracing exposes function arguments in stacktraces which may contain sensitive data like passwords or tokens
- Sending request body to Sentry may expose form data including passwords and personal information
- Database tracing with query arguments can expose sensitive data stored in the database
- User data (email, username, IP address) settings should be carefully considered for GDPR compliance
- The module automatically sanitizes password fields in request data but custom sensitive fields require additional configuration
- When using tunneling, ensure proper access controls as the tunnel endpoint accepts POST requests from users with JavaScript error permission