README

This package integrates Sentry for WordPress. It adds a small amount of glue between a WordPress project and the Sentry 2.x / 3.x SDK. Specifically, it provides boilerplate code to simplify making the call to \Sentry\init() specified in the PHP documentation, as well as tagging additional information while ensuring compatibility with WP-CLI.

Using IS WP Sentry

To initialize Sentry, an instance of this package's SentryLoader class should be initialized: $sentryLoader = new \InteractiveStrategies\WpSentryGlue\SentryLoader();. Do this as early as possible to enable logging for as much of the PHP code as possible, within the limitation that Composer's autoloader must have been included. The wp-config.php file is a good place.

Also call the function SentryLoader->sentryWpContext(); later in your code, after WordPress has initialized. The bottom of wp-config.php is a good place. This adds some default WordPress context to event logging. (WordPress Core version, and User ID & name for logged in users.) An admin dashboard widget will also be added, visible to all users with the manage_options role.

Configuration

At a minimum, you should set a DSN, and configure each server environment with a different environment string. It is recommended you also configure Sentry release tracking.

There are two ways to configure:

Pass an array to the SentryLoader instructions. Example: $sentryLoader = new \InteractiveStrategies\WpSentryGlue\SentryLoader($options_array); SentryLoader's constructor accepts the same options array as Sentry\init().
Install oscarotero/env (^1 || ^2) and provide configuration via environment variables.
- Note that this package cannot read environment variables without oscarotero/env installed.
- Note that any options passed to SentryLoader's constructor cannot be overridden by environment variables.

Set a DSN

The DSN can be set via environment variable SENTRY_DSN.

The DSN looks something like https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@sentry.io/1234567'. It is the one thing Sentry absolutely must have to work, as it tells the Sentry client where to send logged events. The DSN is always available in a project's settings on sentry.io (or your own Sentry host). It should also be displayed elsewhere in the Sentry UI for new projects that do not have events logged yet.

Configure Environment

The environment can be set via environment variable SENTRY_ENVIRONMENT.

Sentry keeps track of which environment each event occurred on. By default, this integration logs Sentry events as coming from a "local" environment. This way, devs working on a local instance of the site who log events to Sentry don't have to worry about remembering to set this variable.

On server environments, the environment should be set to development, production, etc. as appropriate.

Configure Releases

Sentry can also mark what code deployment a site was running at the time an event occurred. This can help you figure out e.g. the earliest commit in which a problem occurred. See official Sentry releases documentation for more details.

The release value can be set via the environment variable SENTRY_RELEASE. This may be a good option on some managed hosts that provide a CLI or API for environment variables, but in other cases an environment variable will be difficult to set, and retain, as part of a deployment process.

Another option is to create a text file named ".sentryrelease" in the site's document root, that contains the release string. In circumstances where an environment variable is hard for a deployment process to manage, writing a file is hopefully a doable option.

Note: using a .sentryrelease file requires the ABSPATH constant to have been set by the time initSentry() is called. Depending on your WordPress setup, ABSPATH may not be set until WordPress is initialized, meaning you would have to initialize SentryLoader later in your execution flow.

Stack Tracing

Can be set via environment variable SENTRY_ALWAYS_STACKTRACE.

Sentry sends stack trace data with any exceptions it logs. By default, however, any other events do not contain stack trace data.

In addition to giving less information to a dev, this also affects how Sentry groups events into issues. As explained by Sentry documentation on issue grouping, Sentry sorts events in part by stack trace. On events without one, it has to fall back to other, simpler methods that tend to group more events together into fewer issues.

A reason not to enable this is that adding stack traces increases the amount of data Sentry has to send when logging events. This increases the risk, if many events are logged while executing the same request, that Sentry itself will cause issues: perhaps a noticeable performance impact, or in the worst case a PHP execution timeout.

WordPress User Data

By default, the logged in WordPress user (if the user is logged in) will be noted in Sentry events, so long as you call SentryLoader::sentryWpContext() in your code (see above).

If you do not want the user logged, set environment variable SENTRY_OMIT_WP_USER_DATA to a truthy value. (The WordPress core version can still be tagged by sentryWpContext(), so you should still call that method.)

Sentry Documentation

If you want to customize Sentry beyond the options provided by this package, the Sentry documentation applies.

Remember that the SentryLoader constructor accepts the same options array as \Sentry\init().

Alternatives

This integration is meant to be a lightweight implementation of server-side Sentry integration capable of being activated early in PHP execution.

Plugins like (WordPress Sentry)(https://wordpress.org/plugins/wp-sentry-integration) have the limitation of loading as part of the standard plugin flow, meaning they will not intercept backend errors early in execution. However, they may offer additional features over this integration. WordPress Sentry, for instance, can manage client-side Sentry integration.

interactivestrategies / wp-sentry-glue

Maintainers

Details