How to monitor your Plone servers with Sentry

use the free Sentry error tracking service to stay on top of production errors

The Sentry.io real-time error tracking service gives you detailed insight into production errors, so that you can often fix them BEFORE your clients even notice a problem and BEFORE their users get upset.

What Sentry provides

Sentry provides a free plan that is more than enough to handle a large number of Plone sites (limited to 1 team member and 5,000 events per day).

Sentry notifies you of errors in a variety of ways (email, by default) and it provides you with a dashboard of all your reported errors, which you can mark as resolved, you can ignore them (for a set amount of time), you can link them to an issue tracker such as GitHub, you can share the detailed error message (scrubbed of private data).

Effects of Sentry

If you are like me, once you start using Sentry, you will:

be amazed at how many errors your Plone site was logging but didn't know about before (not necessarily caused by bugs, but by search engine crawlers looking for things that aren't on the site, bad links from other sites, insufficient privileges because items are still private)
realize that you *can* provide a 100% satisfactory product and service, now that you can see and can fix all the errors, whatever the cause, encountered by your clients and their users
find yourself tracking down and finding and fixing bugs, not only in your sites and server, but sometimes in other code you're using

Boost user and client satisfaction

Other things Sentry does: you can easily customize Plone's default error message page to pop up a nice looking dialog box in which a user can provide their name, email address, and description of what they were trying to do when they encountered an error. Not only is this good for YOU (because it helps you understand what led to the error), it is also FANTASTIC FOR YOUR CLIENT because their users now know that administrators have noticed their problem and are trying to fix it. This is a level of user satisfaction that goes above and beyond what most people have come to accept, which is to suffer in silence.

How to set up Sentry with Plone

How it works: you sign up with Sentry, you declare any number of "projects", each of which gets a unique ID that you use in your buildout.cfg configuration.

In buildout.cfg, you want to add custom error logging configuration so that when an error is logged, it not only gets logged normally to your event.log or instance.log but it also gets sent to Sentry with the unique ID you were assigned.

(There are even finer grained ways of tracking multiple "releases" of each project, but that probably is useful only if you're deploying versions of, say, Facebook.com, which, presumably YOU are not if you are reading my lowly blog!)

Two example buildout configurations

Whether you installed Plone with the Unified Installer or some other buildout-based method, you will have to modify both buildout.cfg and base.cfg to use Sentry.

Plone 4.3 ZEO

In a ZEO Plone 4.3 deployment, which I installed with the Unified Installer, buildout.cfg defines two ZEO clients, [client1] and [client2]. To do that cleanly, buildout.cfg extends base.cfg, which in turn contains a [client_base] section, which both [client1] and [client2] derive from.

We modify [client_base] by adding these lines:

[client_base]
...
event-log-custom =
 %import raven.contrib.zope
 <logfile>
 path ${buildout:var-dir}/${:_buildout_section_name_}/event.log
 level INFO
 </logfile>
 <sentry>
 dsn https://[email protected]/MOREUNIQUEID
 level ERROR
 </sentry>

Your specific "dns" line containing YOURUNIQUEID and MOREUNIQUEID will have come from your Sentry project definition.

You want your "path" value to match that of the "event-log" value defined in [client_base]. I haven't tried this, but you may be able to use a line like path ${event-log} instead of path ${buildout:var-dir}/${:_buildout_section_name_}/event.log

Plone 4.2 ZEO

In contrast, a Plone 4.2 ZEO deployment (also using the Unified Installer) is slightly different: both [client1] and [client2] are defined in base.cfg, so you have to append your custom configuration to both, and the value for "path" is different:

[client1]
...
event-log-custom =
 %import raven.contrib.zope
 <logfile>
 path ${buildout:directory}/var/client1/event.log
 level INFO
 </logfile>
 <sentry>
 dsn https://[email protected]/MOREUNIQUEID
 level ERROR
 </sentry>

and

[client2]
...
event-log-custom =
 %import raven.contrib.zope
 <logfile>
 path ${buildout:directory}/var/client2/event.log
 level INFO
 </logfile>
 <sentry>
 dsn https://[email protected]/MOREUNIQUEID
 level ERROR
 </sentry>

In both cases, the key point here is to ensure your Sentry "path" value matches what was defined for each client. As in the previous section, I haven't tried this, but you may be able to use a line like path ${event-log} instead of path ${buildout:directory}/var/client1/event.log and path ${buildout:directory}/var/client2/event.log

Plone "instance" (non-ZEO) deployments

I haven't tested this myself but the idea is the same. You need to customize logging for the [instance], and that will depend on your buildout.cfg and base.cfg.

Add Raven

You also have to add "raven" to your buildout.cfg eggs:

eggs =
 Plone
 Pillow
 ...
 raven

Run buildout and restart clients

Now run buildout. Once you restart your ZEO clients, when they log an error they will continue appending to the log file defined in the "path" above but will also send the error to Sentry. Depending on how you set up Sentry, you will receive email notifications and you can view a dashboard of your errors.

In all likelihood, you will begin to be able to fix errors (software, user, or other) BEFORE anyone reports them to you, if they even bother to report the errors at all.

Increased client and user satisfaction

Your clients and their users may not even realize how much better a service you are providing them, but you will know, and you will have greatly increased your ability to retain satisfied customers, and that is golden.