documentation for error reporter plugin system

docs/configure.rst

@@ -353,20 +353,40 @@ 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``
 
-rollbar
+.. _error_reporter:
-~~~~~~~
-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::
 
-    # rollbar config
+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 = {
-        'rollbar': {
+        'error_reporter': {
-            'access_token': '32we33a92a5224jiww8982',
+            'rollbar': {
-            'environment': 'Django-Q'
+                'access_token': '32we33a92a5224jiww8982',
+                'environment': 'Django-Q'
+            }
         } 
     }
 
-Please check the Pyrollbar `configuration reference <https://github.com/rollbar/pyrollbar#configuration-reference>`__ for more options.
+For more information on error reporters and developing error reporting plugins for Django Q, see :doc:`errors<errors>`.
-Note that you will need a `Rollbar <https://rollbar.com/>`__ account and access token to use this feature.
+
+.. 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::
+
+..     # rollbar config
+..     Q_CLUSTER = {
+..         'rollbar': {
+..             'access_token': '32we33a92a5224jiww8982',
+..             'environment': 'Django-Q'
+..         }
+..     }
+
+.. 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.
 
 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>