Coverage for superdjango/contrib/errors/__init__.py : 0%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Abstract
3--------
5Capturing errors (exceptions) outside of the development environment is an important aspect of product management and
6user experience. See the `Django documentation on error reporting`_.
8.. _Django documentation on error reporting: https://docs.djangoproject.com/en/stable/howto/error-reporting/
10.. tip::
11 There are many more robust exception handling systems than SuperDjango's Error Capture app. `Sentry`_ for example,
12 is highly recommended (and is itself a Django project). These include a great number of features, but may also
13 require a fee. If you desire a simple, yet effective capture implementation or can't yet justify the cost of a
14 third-party tool, then the Error Capture app may be an alternative.
16.. _Sentry: https://sentry.io/
18Install
19-------
21General
22.......
241) Add ``superdjango.contrib.errors.apps.DefaultConfig`` to ``INSTALLED_APPS``.
262) Add ``superdjango.contrib.errors.middleware.ErrorCaptureMiddleware`` at the end of your middleware list in
27``settings.py``.
293) To enable error capture in development, set ``SUPERDJANGO_ERROR_CAPTURE_DEBUG = True``. This is useful for testing
30customer error handlers as well as see a preview of your error templates, but it can be a hindrance to troubleshooting.
324) To control how often an error may repeat, set ``SUPERDJANGO_ERROR_CAPTURE_REPEAT_SECONDS``. The default is ``3600``, or
33one (1) hour.
355) Specify one or more error capture handlers using ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS`` and provide the required
36settings for each one. See below.
38.. tip::
39 The last error handler specified is returned as the result if it is an ``HttpResponse`` instance.
41Bitbucket Handler
42.................
44Create a Bitbucket issue based on an exception.
46Returns: a dictionary with the ``issue_url``.
481) Install bitbucket-python: ``pip install bitbucket-python``
502) ``superdjango.contrib.errors.apps.DefaultConfig`` must be included in ``INSTALLED_APPS``.
523) Identify the repo using the ``SUPERDJANGO_ERROR_CAPTURE_BITBUCKET_REPO`` setting.
544) Identify the owner using the ``SUPERDJANGO_ERROR_CAPTURE_BITBUCKET_OWNER`` setting.
565) Provide a email using the ``SUPERDJANGO_ERROR_CAPTURE_BITBUCKET_EMAIL`` setting.
586) Provide a password using the ``SUPERDJANGO_ERROR_CAPTURE_BITBUCKET_PASSWORD`` setting.
607) Add ``superdjango.contrib.errors.backends.Bitbucket`` to ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS``.
62CSV Handler
63...........
65Basic data is written to ``current.csv`` in th output path, and tracebacks are written as text files in the
66``tracebacks/`` directory of the output path.
68Returns: A dictionary with the ``issue_url`` if the error views are enabled (below). Otherwise, the dictionary includes
69the ``identifier`` of the error.
71.. note::
72 Each error is assigned a unique ID which exists in the CSV and is used for the file name of the traceback file.
741) To log errors to a CSV file, add ``superdjango.contrib.errors.backends.CSV`` to
75 ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS``.
772) You must also set ``SUPERDJANGO_ERROR_CAPTURE_OUTPUT_PATH`` to the path were the data is stored. For example:
78 ``SUPERDJANGO_ERROR_CAPTURE_OUTPUT_PATH = os.path.join(BASE_DIR, "../data", "errors)``.
803) Optionally set up views.
82To access errors from within the project's UI, load the views.
84.. code-block:: python
86 # main/urls.py
87 from superdjango.contrib.errors.views import CSVErrorViewSet
89 urlpatterns = [
90 # ...
91 path("errors/", include(CSVErrorViewSet().get_urls())),
92 ]
94Email Handler
95.............
97Send an exception via email.
99Returns: ``None``
101.. important::
102 In addition to the settings below, you must also configure `Django to send email`_.
104.. _Django to send email: https://docs.djangoproject.com/en/stable/ref/settings/#email-backend
1061) ``superdjango.contrib.errors.apps.DefaultConfig`` must be included in ``INSTALLED_APPS``.
1082) Set the "from address" using ``SUPERDJANGO_ERROR_CAPTURE_FROM_EMAIL``.
1103) Set a list of email addresses to which the info is sent using ``SUPERDJANGO_ERROR_CAPTURE_EMAILS``.
1124) Add ``superdjango.contrib.errors.backends.Email`` to ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS``.
114GitHub Handler
115..............
117Create a GitHub issue based on an exception.
119Returns: A dictionary with the ``issue_url``.
1211) Install PyGithub: ``pip install PyGithub``
1232) ``superdjango.contrib.errors.apps.DefaultConfig`` must be included in ``INSTALLED_APPS``.
1253) Identify the repo using the ``SUPERDJANGO_ERROR_CAPTURE_GITHUB_REPO`` setting.
1274) Provide a token using the ``SUPERDJANGO_ERROR_CAPTURE_GITHUB_TOKEN`` setting.
1295) Add ``superdjango.contrib.errors.backends.GitHub`` to ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS``.
131Model Handler
132.............
134Save an error report to the local database.
136Returns: A dictionary with the ``issue_url`` if the error views are enabled (below). Otherwise, ``None``.
1381) Create an app and extend :py:class:`superdjango.contrib.errors.models.ErrorModel`.
140.. tip::
141 You can override the ``log()`` method to handle any custom fields you define on your extended model.
1432) Add the dotted path to this model to settings using ``SUPERDJANGO_ERROR_CAPTURE_MODEL_NAME``.
1453) Add ``superdjango.contrib.errors.backends.GitHub`` to ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS``.
1474) Optionally set up views.
149To access errors from within the project's UI, load the views.
151.. code-block:: python
153 # main/urls.py
154 from superdjango.contrib.errors.views import ModelErrorViewSet
156 urlpatterns = [
157 # ...
158 path("errors/", include(ModelErrorViewSet().get_urls())),
159 ]
161.. important::
162 You *cannot* use ``ModelErrorViewSet`` *and* ``CSVErrorViewSet`` at the same time because these views utilize the
163 same names. You *can* use both error handlers at once, but only one may be used for error views.
165You may also create a custom UI instead, using SuperDjango UI.
167.. code-block:: python
169 # myapp/ui.py
170 from .models import Error
171 from superdjango import ui
173 class ErrorUI(ui.ModelUI):
175 detail_options = ui.DetailOptions(
176 "name",
177 "added_dt",
178 "path",
179 "line",
180 "traceback",
181 )
182 list_options = ui.ListOptions(
183 "name",
184 "added_dt",
185 "path",
186 "line",
187 )
189 class ErrorMenu(ui.Menu):
190 items = [
191 ErrorUI,
192 ]
193 label = "Errors"
194 prefix = "errors"
196 ui.site.register(ErrorMenu)
198Usage
199-----
201Filtering Errors
202................
204Internally, the error capture system makes use of Django's ``django.views.debug.ExceptionReporter`` class. This provides
205support for Django's `built-in error filtering`_ functionality.
207.. _built-in error filtering: https://docs.djangoproject.com/en/table/howto/error-reporting/#filtering-error-reports
209Creating Your Own Error Handler
210...............................
212An error handler should extend :py:class:`superdjango.contrib.errors.backends.base.ErrorHandler`.
214To perform additional work, the ``handle()`` method is overridden. See the existing handlers for examples.
216Once this is done, the custom handler may be added to the ``SUPERDJANGO_ERROR_CAPTURE_HANDLERS`` list in the
217``settings.py`` file.
219Overriding Error Templates
220..........................
222The templates used for creating and displaying errors may be overridden by providing your own templates in an app that
223is loaded above ``superdjango.contrib.errors.apps.DefaultConfig``.
225See ``superdjango/contrib/errors/templates/errors/`` for the templates that are defined for the various handlers.
227Known Issues
228............
230If you have an app that catches all remaining URLs (as with some CMS apps, including Wagtail), then ``DoesNotExist``
231errors will be captured for things like the favicon. You can of course simply provide the missing file(s).
233You may also add ``django.middleware.common.BrokenLinkEmailsMiddleware`` to your middleware and define the links that
234should be ignored. For example:
236.. code-block:: python
238 # settings.py
239 import re
240 IGNORABLE_404_URLS = [
241 re.compile(r'\.(php|cgi)$'),
242 re.compile(r'^/phpmyadmin/'),
243 re.compile(r'^/apple-touch-icon.*\.png$'),
244 re.compile(r'^/favicon\.ico$'),
245 re.compile(r'^/favicon\.ico/$'),
246 re.compile(r'^/robots\.txt$'),
247 ]
249"""
250__author__ = "Shawn Davis <shawn@superdjango.com>"
251__maintainer__ = "Shawn Davis <shawn@superdjango.com>"
252__version__ = "0.3.0-x"