Drupal error tracking with Sentry

Drupal error tracking with Sentry: what it catches and when to use it

Sentry collects grouped, deduplicated errors from both PHP and JavaScript on a Drupal site, and the Raven module is the contributed connector that sends them. Without it, a PHP fatal error or a broken script may show up only in the web server log, the Drupal watchdog table or a user's support email, often hours after a release has gone out. Sentry turns repeated occurrences into a single issue with a count, a first-seen time, the release it appeared in and the stack trace, so the team can see within minutes that a new error started with the latest deployment. The effect is most useful when the site ships often, when the site is in its first months after launch, or when errors affect only some users, such as one role, one language, one browser or one set of content. Those cases are hard to reproduce by hand and easy to miss in raw logs.

Teams should decide before installation who receives alerts, which environments report (production only, or staging too), and which release identifier each deployment sends, because Sentry can only tell new errors from old ones when releases are tagged consistently. Confirm the Raven module version that supports your Drupal release, since Drupal 10 and Drupal 11 have different PHP minimums and the Drupal.org project page for the module and Sentry's own PHP and JavaScript SDK documentation define the exact configuration keys, DSN handling and browser setup. Your team should also check whether your Sentry deployment is hosted by Sentry or self-managed, because that choice changes who maintains the service and where error data is stored.

The value of error tracking depends on the handling around it. A new issue that appears after a deployment should lead to a rollback decision or a fix within the normal release routine, and the team should agree on who owns triage. Error payloads can contain form values, URLs with query strings, user names or session details, so the filtering rules described later on this page must be in place before the first production event is sent. Ask any partner to show how they will test those rules on your own staging site and how alert noise will be reduced during the first weeks of operation.

Which errors reach Sentry from a Drupal site

A Sentry project for Drupal receives events from several places, and each one sees a different slice of the failure. Knowing which source catches what tells you where a missing event is hiding and which gaps need a second tool.

Server-side PHP exceptions and fatals

Uncaught exceptions thrown by custom modules, contributed modules and core are the most common events a Raven-based setup captures. Fatal errors, such as memory exhaustion or a missing class during a request, end the PHP process, so the SDK must hook shutdown handling to report them. Check that fatal errors from a test route actually appear in Sentry before you trust the setup. Errors that are caught and suppressed by custom code never reach Sentry unless someone reports them explicitly.

Drupal log messages routed to Sentry

Drupal writes watchdog-style messages through the logger channels, and Raven can forward those at chosen severity levels. This catches problems that never throw, such as failed cron runs, payment callback warnings or a module logging a notice at error level. Expect volume: forwarding every notice floods the project and buries real faults. Choose a minimum level per channel and review the noisiest channels after the first week.

Browser JavaScript errors

Errors in theme scripts, Drupal behaviors and third-party widgets happen in the visitor's browser, where PHP sees nothing. A browser SDK captures uncaught exceptions and unhandled promise rejections, along with the page URL and browser version. It misses errors blocked by content security policy or ad blockers, and it will not see failures in scripts that load before the SDK initializes. Confirm the DSN and CSP settings with your security team before enabling it on public pages.

Release and environment metadata

Every event carries tags such as environment and release, which decide whether an error is new after a deploy or a long-standing issue. Set the release from your build pipeline, not by hand, so each Composer or Git deployment maps to one identifier. Without it, alerts for new errors after a release cannot be scoped. Also confirm that production, staging and local events are separated, because mixed environments distort both alert rules and issue counts.

Failures before Drupal bootstraps

Some failures never reach Drupal code. Errors in the web server configuration, PHP-FPM startup, a broken settings.php include or a cache layer that serves a stale or error page can all bypass the SDK. Reverse proxies and CDNs can also return cached error responses that the origin never logs. Pair Sentry with web server logs and uptime checks from outside the site, so you can see failures the SDK cannot.

Configuration options and when each fits

This table compares the choices that shape a Drupal to Sentry integration, from where Sentry runs to how much data is sent. Read each row against your traffic, data rules and the team that will triage alerts. The main takeaway is that hosting location and personal data handling decide more than the module settings do, so settle them before enabling capture on production.

Decision	Option	Trade-off	When it fits
Sentry hosting	Hosted Sentry service	Lowest operational load and fastest setup, but error payloads leave your network and cost scales with event volume	Teams without capacity to run Sentry, and where error data may leave your environment under your data rules
Sentry hosting	Self-hosted Sentry instance	Full data control and no per-event vendor dependency, but you own upgrades, storage, backups and uptime	Regulated sites that cannot send stack traces or request data to a third party and have ops staff to run it
Error sources	PHP capture only	Lower noise and simpler consent review, but client-side exceptions stay invisible	Back-end-heavy sites with few custom front-end scripts
Error sources	PHP plus JavaScript	Catches browser errors from themes and scripts, but adds more events and needs careful filtering of browser data	Sites with significant custom JavaScript or third-party widgets that fail in the browser
Tagging	Environment and release tags	Small setup effort that makes new errors after a deploy easy to isolate and separates staging noise from production	Almost every project, with the release value set by your build pipeline
Traffic volume	Low or no sampling	Complete visibility, but high-traffic sites can generate large event volumes and cost	Low-traffic sites or early rollout periods
Traffic volume	Reduced sample rate	Lower volume and cost, but rare errors may be missed unless you watch the sample rate	High-traffic sites where common errors repeat and rare errors are covered by logs
Drupal logs	Capture Drupal log messages	Broader context for investigations, but warnings and notices add noise and may carry personal data	Teams that have tuned log levels and a filter for personal data
Drupal logs	Capture exceptions only	Quieter alert queue and fewer data risks, but some diagnostic context stays in Drupal's own logs	Sites that already centralize Drupal logs with syslog or another platform

Setting up Drupal error tracking with Sentry

This sequence takes a Drupal site from an empty Sentry project to verified PHP and JavaScript error capture, with secrets kept out of exported configuration and each event tagged with the environment and release that produced it. It ends with a deliberate test error that proves the whole path works before production traffic relies on it.

Create the Sentry project and choose hosting
Create a project in Sentry for the Drupal site, with a separate project or clearly named environment for each site and tier. Decide whether to use Sentry's hosted service or a self-hosted Sentry instance in infrastructure you control, based on where error payloads may contain data and what your data residency rules allow. Ask the vendor to confirm current plan limits and retention before you commit. Done when the project exists, you hold a DSN for it, and the hosting decision is written down with its owner.
Install the Raven module in staging with Composer
In a staging environment built from the same Composer lockfile as production, add the Raven module through Composer, enable it with Drush, and confirm the module list shows it as enabled. Pin the version in composer.json so updates go through your normal release review. Check that the module's compatibility with your Drupal core version is listed on its Drupal.org project page before installing. Done when the module is enabled on staging and the change is committed to version control.
Store the DSN and environment outside exported configuration
Place the DSN and the environment name in environment variables or your secrets manager, and have the site read them at runtime rather than storing them in the configuration sync directory. Confirm with a config export that no DSN value appears in the exported YAML. Restrict who can read the secret in each environment. Done when a configuration export on staging contains no DSN and the site still reports the DSN as configured.
Enable PHP error capture
Turn on PHP error and exception reporting in the Raven settings for staging, and set the environment name so events separate staging from production. Choose the sample rate deliberately for each environment instead of accepting a default you have not reviewed. Trigger a warning on a non-critical staging page and confirm it appears in the Sentry issue stream with the expected environment, the PHP stack trace and the Drupal request path. Done when a PHP event shows the right environment and a readable stack trace.
Enable JavaScript capture and upload source maps
Enable the browser-side Sentry SDK through the module settings or theme library, and confirm that the browser SDK loads only on the pages you intend to monitor. If your front-end build is minified, generate source maps during the build and upload them to Sentry with the release identifier so stack frames map back to source files. Throw a test error from a page script and confirm the event shows a mapped stack trace, not minified line numbers. Done when a JavaScript event shows original file names and line numbers.
Tag events with the Drupal release
Set the release identifier in the same build step that deploys the site, using the Git tag or build number your deployment already produces, and pass it to both the PHP and JavaScript configuration. Deploy to staging and confirm that new events carry the release value that matches the deployed build. Check that a rollback changes the reported release. Done when a staging event shows the release that was just deployed, and the release name is visible in the Sentry release list.
Review personal data in events before production
Before enabling production, review a sample of events and confirm that request bodies, cookies, form fields and user details are filtered or excluded as your data protection requirements require. Configure data scrubbing in Sentry and in the Raven settings, and confirm that email addresses and session identifiers do not appear in the event payload. Document the filters and who approved them. Done when a sample event from a form submission contains no personal data in its fields.
Trigger a deliberate test error in production
Add a clearly named test route or use a temporary endpoint that throws a known exception, deploy it to production during a quiet period, trigger it once, and confirm the event arrives with the production environment, the correct release and a filtered payload. Remove the test route, deploy again, and confirm it is gone. Set an alert rule in Sentry so that new issues after a release notify the on-call channel. Done when the test event is visible in production and the alert fires for a new issue.

How to filter personal data before errors leave the site

Error payloads are a privacy risk in their own right. When Drupal sends an exception to Sentry, the event can carry far more than a stack trace: form values from a failed submission, email addresses in the request context, session or cookie data, client IP addresses and query strings that hold tokens or search terms. For a site that handles patient, customer or citizen data, each of those fields can make the error tracker a store of personal data under GDPR, HIPAA or a sector rule, with its own retention, access and processor obligations. Decide before go-live which fields may leave the site at all, and record that decision as part of the data inventory for the site.

The practical control is a before-send step that runs inside the Drupal application, so data is cleaned before the event is transmitted. A typical filter scrubs values under known field names (such as pass, mail, tax_id or your own sensitive keys), drops request bodies entirely for sensitive routes such as login, registration, payment and patient forms, strips query parameters, and replaces user identifiers with a stable pseudonym or removes them. Confirm with the Raven module documentation and the Sentry SDK version in use which hook or option carries the before-send logic, since the hook names and configuration keys depend on the module version and should be checked against the release you install, not against older examples.

Test the filters before any production event is sent. Build a set of sample events that include a fake email address, a password field, a session cookie, a token in a query string and a form on a sensitive route, then send them from staging and inspect what arrives in Sentry. Keep the test set under version control so that every module update, Sentry SDK change or new form gets re-checked. Ask your partner or internal team to confirm that the test covers JavaScript errors as well as PHP errors, because browser events are scrubbed separately and are easy to overlook.

Alerting on new errors after releases with Sentry

The first release after launch is the period when errors are most likely to be new, because real traffic, real content and real integrations meet the code for the first time. Keep alerting tight and temporary: every new issue should reach a named owner quickly, and the team should review the release tag against the deploy record within the same working day.

New issue rules: Create an alert for any issue first seen in the production environment with the release tag set to the go-live build, routed to the on-call channel and the application owner.
Regression rules: Alert when a previously resolved issue reappears in a later release, since a fix that did not hold is a common launch problem.
Issue spike rules: Set a spike alert on the top PHP and JavaScript error groups so a single failing form or theme script does not go unnoticed during peak traffic.
Release tagging: Set release in the Raven configuration to the deployed Git tag or build ID, and confirm in Sentry that every event carries it before go-live.
Exit criteria: Agree with the client when the tighter rules will be relaxed, and record who approved that change.

Before go-live, confirm that the alert recipients are reachable outside business hours and that the release tag appears on test events from the production build.

Staging environments, content editor tools and administrative screens generate errors that are real but usually not urgent, such as failed previews, incomplete test content or expected validation messages. If they share alert rules with production, the on-call team stops reading alerts. Keep these environments in Sentry but route them differently and suppress known noise narrowly.

Separate environments: Set the environment value to staging, editor or production, and scope alert rules to production for paging and to staging for a weekly digest.
Recipients: Send staging alerts to the development team and content editor issues to the Drupal site owner, not to the on-call rotation.
Narrow suppression: Ignore known third-party noise, such as a browser extension or an analytics script failing to load, by matching the exact error message or source file, not by muting a whole category.
Keep new failures visible: Do not suppress all JavaScript errors from a theme or module; keep the new issue rule active so a fresh failure in the editor still alerts.
Review suppression rules: Revisit each ignore rule after every monthly release, since a fix or upgrade can change the message that the rule matches.

Sample a few suppressed events each month to confirm that the rules hide only the noise you intended.

Security and operational considerations

An error tracker sits in the request path and handles data that often includes user details, form values and stack traces. The four concerns below are secrets handling, access, data location and retention, and whether the monitoring itself stays dependable, and they need to be decided together before the first event is sent.

Treat the DSN as a secret

The DSN identifies the Sentry project and lets any holder submit events to it. Keep it out of exported configuration and version control, and load it from the environment or a secrets store so it can be rotated without a code release. Because the DSN is also visible to browsers when JavaScript error reporting is enabled, plan for a separate public key per front end and check for abuse such as event flooding that would consume quota. Ask who can rotate keys and how a rotation is rolled out across environments.

Control who sees event data

Stack traces, local variables and request context can expose database fragments, session identifiers and internal paths. Limit Sentry project membership by role, separate production from staging projects, and decide who may view raw payloads and who may only see grouped issues. Confirm how your hosted or self-hosted Sentry handles team-based permissions, SSO and audit logs before onboarding developers outside the core team, including contractors.

Set retention and data location

Decide how long events are kept, where they are stored and which regions or hosting boundaries apply. For hosted Sentry, confirm the data residency options available on your plan and the retention period set for your organization. For self-hosted Sentry, the storage location, backup scope and deletion process are your responsibility. Align these choices with your records retention schedule and with any contract that restricts where personal data may be processed.

Filter personal data before it leaves

Scrubbing is most reliable when it happens in the Drupal process, before transmission. Configure the before-send hook to remove password fields, tokens, cookies, authorization headers and form values that contain personal data, and turn off default user context such as email addresses where they are not needed. Test the filter with sample exceptions from forms and login pages, and review a few real events in staging after every change.

Plan quota, sampling and outage behavior

Error tracking becomes an operational dependency. A release with a loop or a bot crawling missing pages can exhaust event quota and hide later errors, so set sampling rates and rate limits per project and alert when quota use spikes. Confirm that the Raven integration sends events asynchronously or with short timeouts, so a slow or unreachable Sentry endpoint does not delay page responses. Check that Drupal keeps serving pages when Sentry is down, and test that behavior deliberately.

Keep the module patched

Sentry integration code runs on every request and every error path, so a vulnerability in the Raven module or in Drupal core affects the whole site. The Drupal Security Team publishes advisories for core and contributed projects and uses scheduled Wednesday security release windows. Subscribe to advisories for the modules you run, include the Raven update in your monthly maintenance cycle, and test error capture on staging after each update.

What buyers ask before hiring help with Sentry on Drupal

What drives the effort of a Sentry integration on Drupal?

The effort follows the number of sites and environments, how much custom code sits in front of the error stream, and how complex the JavaScript build is. A single site with stock modules and one environment is the simplest case. Each additional multisite install, each separate staging or regional environment, and each custom module that raises errors adds configuration and testing. Filtering requirements and alert design add further work, because every rule that drops or routes an event must be written, tested and explained to the people who depend on it. Ask any partner to break the quote down by these drivers.

How long does Sentry error tracking take to set up?

Duration depends on the same drivers as cost: environment count, custom code, JavaScript pipeline and the depth of filtering and alerting. A basic PHP-only setup on one environment is much shorter than a multisite estate with source maps, release tagging and personal data filters. No fixed duration applies to every project, so ask for a timeline that lists the environments, the phases and the sign-off points in writing before work starts. Most engagements are fixed-scope, which means the timeline is agreed alongside the deliverables.

What does our team need to provide for the work?

Plan on providing four things. First, administrator access to the Sentry organization and project so that DSNs, teams, alert rules and release settings can be created. Second, a staging environment that mirrors production closely enough to test filters and source maps before any change reaches live traffic. Third, a documented release process, including who tags releases and how deployments are recorded, because release-aware alerting depends on it. Fourth, a named data owner who signs off on what counts as personal data and which fields are removed before events leave the site.

Can an internal Drupal developer set up Sentry alone?

A developer who already maintains Drupal can install the Raven module and send PHP errors to a project with basic settings. The harder parts are the ones that need coordination: writing scrubbing rules that satisfy the data owner, wiring JavaScript source maps into the build, tagging releases from the deployment pipeline and tuning alerts so that the team is not flooded. If your staff has the time and a clear sign-off path, an internal build is workable. If the same people also carry the site roadmap, an outside review of the filter rules often catches gaps that internal teams overlook.

What personal data can end up in Drupal error reports?

Error events can carry request URLs, query strings, form values, user identifiers, IP addresses and stack trace variables, depending on how the application and the SDK capture context. Form submissions on registration or payment pages are a common source of unintended data. Define the fields that must never leave the site, configure the SDK to remove or mask them before sending, and test with deliberately invalid inputs on staging. Confirm with your privacy and legal teams which regional or sectoral rules apply, because DeployOpen does not provide legal advice and does not certify compliance.

What recurring work follows the initial setup?

Sentry configuration needs regular attention after launch. Module updates from Drupal's monthly bugfix and security windows can change how errors are reported, so the Raven module and the SDK need to be tested with each release. Filter rules should be reviewed whenever forms, integrations or data fields change. Alert rules need tuning as the team learns which issues matter, and old rules should be retired. Ask any partner whether this work is included in the project or sold as a retainer, and what the review cadence will be.

Does Sentry itself need a paid plan or self-hosted server?

Drupal and the Raven module are free and open source under GPL-2.0-or-later, so the Drupal side carries no license fee. Sentry is a separate product, and your choice between its hosted service and a self-managed deployment changes your costs and data residency. Confirm current plan terms, data region options and retention with the vendor before you commit, since these details change. Your quote should show any Sentry subscription or hosting cost separately from the implementation fee.

Limits to confirm in your environment

Error tracking depends on four limits that change independently of your code: the Drupal version and its module support, the PHP runtime, the way JavaScript reaches Sentry through your theme, and the Sentry plan that caps what you can ingest and keep. Confirm each one against its owner's documentation before you commit to a design.

Raven module compatibility with your Drupal version

Check that the Raven module release you plan to use declares support for the Drupal core version you run. Drupal 11 is the current major version, and Drupal 10 reaches end of life on December 9, 2026, according to the core release schedule, so a site that stays on Drupal 10 will need a Sentry integration path it can keep patched through that date. Confirm the supported core range on the module's Drupal.org project page, and re-check it before each core upgrade, since a module can lag a new major release.

PHP version under the Drupal requirements

Your PHP runtime sets the ceiling for your Drupal version and for the Sentry PHP SDK your build pulls in. Drupal 10 requires PHP 8.1 or later, Drupal 11 requires PHP 8.3 or later, and Drupal 12 requires PHP 8.5 or later, so an older PHP build on a shared host can block both the upgrade and the SDK. Confirm the PHP version on each environment, including workers that run cron and queues, and check the Sentry PHP SDK's own minimum version before you pin it in Composer.

JavaScript capture through your theme and assets

Browser error capture depends on how your theme loads scripts. Sites that bundle assets with a build tool, aggregate CSS and JavaScript, or add a strict Content Security Policy can stop the Sentry browser SDK from loading or reporting errors. Test on a staging build with the production asset settings, trigger a deliberate error from a logged-out page and an authenticated page, and confirm the event appears in Sentry with a readable stack trace and source maps.

Sentry plan limits for events and retention

Event volume, retention period and the number of projects or seats are set by your Sentry plan, not by Drupal. A noisy error loop or a bot crawling missing pages can exhaust a monthly quota within hours, and then real incidents go unrecorded. Ask for the current event quota, retention period, rate limits and any overage behavior in writing, and confirm them in the Sentry pricing and documentation pages before you set sampling rates and alert thresholds.

How DeployOpen works on this

DeployOpen plans and builds Drupal error tracking with Sentry inside your own infrastructure, from the scope agreed in writing through to documented handover. Engagements are fixed-scope, and ongoing support is available as a retainer once the integration is live.

How we scope

Inventory the Drupal version, PHP runtime and hosting so the Sentry SDK path matches your stack
Agree which PHP and JavaScript error sources are in scope and which environments report
Define the personal data fields to strip before events leave your network, with your privacy team
Confirm whether your Sentry instance is cloud-hosted or self-hosted and who holds the project keys

How we build

Install and configure the Raven module, then set DSN, environment and release values through configuration
Add frontend error capture for theme and JavaScript code paths agreed during scoping
Write and test scrubbing rules so sensitive form, session and user values never reach Sentry
Configure alert rules for new issues after each release, tested against a staging deployment first

How we hand over

Deliver a runbook covering DSN rotation, environment tagging, release naming and alert ownership
Document the scrubbing rules, their tests and the review steps needed when new fields are added
Walk your operations and security staff through triaging an issue from alert to fix
Hand over configuration as code in your repository so changes go through your normal review

How we support

Review error volume and alert noise with your team after the first release cycles
Update the Raven module and SDK components alongside your monthly Drupal update routine
Re-test scrubbing rules after Drupal core or module upgrades that change error output
Offer ongoing support and continuous checks as a retainer, priced from the written scope

Drupal error tracking with Sentry