Merge pull request #261 from danielwelch/error-reporter

Error reporter

docs/configure.rst

@@ -353,6 +353,26 @@ scheduler
 You can disable the scheduler by setting this option to ``False``. This will reduce a little overhead if you're not using schedules, but is most useful if you want to temporarily disable all schedules.
 Defaults to ``True``
 
+.. _error_reporter:
+
+error_reporter
+~~~~~~~~~~~~~~
+You can redirect worker exceptions directly to various error reportes (for example, `Rollbar <https://rollbar.com/>` or `Sentry <https://docs.sentry.io/>`) by installing Django Q with the necessary `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`.
+
+To enable installed error reporters, you must provide the configuration settings required by an error reporter extension::
+
+    # error_reporter config--rollbar example
+    Q_CLUSTER = {
+        'error_reporter': {
+            'rollbar': {
+                'access_token': '32we33a92a5224jiww8982',
+                'environment': 'Django-Q'
+            }
+        } 
+    }
+
+For more information on error reporters and developing error reporting plugins for Django Q, see :doc:`errors<errors>`.
+
 rollbar
 ~~~~~~~
 You can redirect worker exceptions directly to your `Rollbar <https://rollbar.com/>`__ dashboard by installing the python notifier with ``pip install rollbar`` and adding this configuration dictionary to your config::
@@ -368,6 +388,10 @@ You can redirect worker exceptions directly to your `Rollbar <https://rollbar.co
 Please check the Pyrollbar `configuration reference <https://github.com/rollbar/pyrollbar#configuration-reference>`__ for more options.
 Note that you will need a `Rollbar <https://rollbar.com/>`__ account and access token to use this feature.
 
+
+.. note::
+    The ``rollbar`` setting is included for backwards compatibility, for those who utilized rollbar configuration before the ``error_reporter`` interface was introduced. Note that Rollbar support can be configured either via the ``rollbar`` setting, or via the ``django-q-rollbar`` package and enabled via the ``error_reporter`` setting above.
+
 cpu_affinity
 ~~~~~~~~~~~~
 

docs/errors.rst

@@ -0,0 +1,9 @@
+Errors
+------
+.. py:currentmodule:: django_q 
+
+Django Q uses a pluggable error reporter system based upon python `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`, allowing anyone to develop plugins for error reporting and monitoring integration. Currently implemented examples include `Rollbar <https://rollbar.com/>` and `Sentry <https://docs.sentry.io/>`).
+
+Error reporting plugins register a class which implements a ``report`` method, which is invoked when a Django Q cluster encounters an error, pasing information to the particular service. Error reporters must be :ref:`configured<error_reporter>` via the ``Q_CLUSTER`` dictionary in your :file:`settings.py`. These settings are passed as kwargs upon initiation of the Error Reporter. Therefore, in order to implement a new plugin, a package must expose a class which will be instantiated with the necessary information via the ``Q_CLUSTER`` settings and implements a single ``report`` method.
+
+For example implementations, see `django-q-rollbar <https://github.com/danielwelch/django-q-rollbar>` and `django-q-sentry <https://github.com/danielwelch/django-q-sentry>`

docs/index.rst

@@ -42,6 +42,7 @@ Contents:
     Cluster <cluster>
     Monitor <monitor>
     Admin <admin>
+    Errors <errors>
     Signals <signals>
     Architecture <architecture>
     Examples <examples>