Add Sentry integration

doc/index.rst

@@ -23,6 +23,7 @@ Getting started with spinach:
    :maxdepth: 1
 
    user/install
+   user/integrations
    user/signals
    user/design
    user/faq

doc/user/integrations.rst

@@ -0,0 +1,25 @@
+.. _integrations:
+
+Sentry
+======
+
+With the Sentry integration, failing jobs can be automatically reported to
+`Sentry <https://sentry.io>`_ with full traceback, log breadcrumbs and job
+information.
+
+The integration requires `Raven <https://pypi.python.org/pypi/raven>`_, the
+Sentry client for Python::
+
+    pip install raven
+
+The integration just needs to be registered before starting workers::
+
+    from raven import Client
+    from spinach.contrib.sentry import register_sentry
+
+    raven_client = Client('https://sentry_dsn/42')
+    register_sentry(raven_client)
+
+    spin = Spinach(MemoryBroker())
+    spin.start_workers()
+

spinach/contrib/sentry.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from spinach import signals
+
+
+def register_sentry(raven_client, namespace: Optional[str]=None):
+    """Register the Sentry integration.
+
+    Exceptions making jobs fail are sent to Sentry. Note that exceptions
+    resulting in the job being retried are not sent to Sentry.
+
+    :param raven_client: configured Raven client used to sent errors to Sentry
+    :param namespace: optionally only register the Sentry integration for a
+                      particular Spinach instance.
+    """
+
+    @signals.job_started.connect_via(namespace)
+    def job_started(*args, job=None, **kwargs):
+        raven_client.context.activate()
+        raven_client.transaction.push(job.task_name)
+
+    @signals.job_finished.connect_via(namespace)
+    def job_finished(*args, job=None, **kwargs):
+        raven_client.transaction.push(job.task_name)
+        raven_client.context.clear()
+
+    @signals.job_failed.connect_via(namespace)
+    def job_failed(*args, job=None, **kwargs):
+        raven_client.captureException(
+            extra={attr: getattr(job, attr) for attr in job.__slots__}
+        )