=============
Error Tracker
=============

**Full featured error tracking module for Python apps supports Flask and Django**

.. image::  https://img.shields.io/pypi/v/error-tracker.svg?color=dark-green
    :target: https://pypi.org/project/error-tracker

.. image::  https://img.shields.io/pypi/pyversions/error-tracker.svg?color=dark-green
    :target: https://pypi.org/project/error-tracker

.. image:: https://img.shields.io/github/license/sonus21/error-tracker.svg?color=dark-green
    :target: https://github.com/sonus21/error-tracker/blob/master/LICENSE.txt

.. image:: https://travis-ci.org/sonus21/error-tracker.svg?branch=master
    :target: https://travis-ci.org/sonus21/error-tracker

.. image:: https://coveralls.io/repos/github/sonus21/error-tracker/badge.svg?color=dark-green
    :target: https://coveralls.io/github/sonus21/error-tracker

Introduction
------------
ErrorTracker is a batteries-included app and extensions for python app, that can track errors, send notification, mask sensitive data and capture frames data.

It plays nicely with `Django <https://www.djangoproject.com/>`_ and `Flask <http://flask.pocoo.org/>`_

Simple to use  extension that lets you add error recording interfaces to Python applications.
It's implemented in such a way that the developer has total control of the resulting application.

Out-of-the-box, Error Tracker plays nicely with various ORM's, including

- `SQLAlchemy <http://www.sqlalchemy.org/>`_,
- `MongoEngine <http://mongoengine.org/>`_,
- `Django ORM <https://tutorial.djangogirls.org/en/django_orm/>`_


It also boasts a simple Model management interface.

The biggest feature of ErrorTracker is flexibility. To start off with you can create a very simple application in no time,
with exception monitor enabled, but then you can go further and customize different aspects.

ErrorTracker is an active project, well-tested and production ready.

Installation
------------
To install ErrorTracker, simply::

    pip install error-tracker


Features
--------
- Sensitive data( like *password*, *secret* ) Masking
- Record all the frames ( frame data are stored in JSON format so that it can be analyzed later)
- Unique URL generation
- Number of times the exception occurred and first/last time of exception
- Sending notifications with exception details
- Record different types of exception like 500 or 404 etc
- Raise or update ticket in Jira/Bugzilla etc by ticketing interface.

Usage
-----

Flask App configuration
=======================

.. code::

    ...
    APP_ERROR_SEND_EMAIL = True
    APP_ERROR_RECIPIENT_EMAIL = ('example@example.com',)
    APP_ERROR_SUBJECT_PREFIX = "Server Error"
    APP_ERROR_EMAIL_SENDER = 'user@example.com'



app.py

.. code::

    from flask import Flask
    from flask_mail import Mail
    import settings
    from error_tracker import AppErrorTracker, NotificationMixin
    from flask_sqlalchemy import SQLAlchemy
    ...
    app = Flask(__name__)
    app.config.from_object(settings)
    db = SQLAlchemy(app)
    class Notifier(Mail, NotificationMixin):
        def notify(self, request, exception,
                   email_subject=None,
                   email_body=None,
                   from_email=None,
                   recipient_list=None):
            message = Message(email_subject, recipient_list, email_body, sender=from_email)
            self.send(message)
    mailer = Notifier(app=app)
    error_tracker = AppErrorTracker(app=app, db=db, notifier=mailer)

    ....

    ....
    # Record exception when 404 error code is raised
    @app.errorhandler(403)
    def error_403(e):
        error_tracker.capture_exception()
        # any custom logic

    # Record error using decorator
    @app.errorhandler(500)
    @error_tracker.track_exception
    def error_500(e):
        # some custom logic
    ....


Django App Usage
================

We need to update settings.py file as

-  Add app to installed apps list
-  Add Middleware for exception tracking. This should be added at the end so that it can process exception 1st in the middleware call stack.
-  Other configs related to notification

Sample Code


.. code::

    ...
    APP_ERROR_RECIPIENT_EMAIL = ('example@example.com',)
    APP_ERROR_SUBJECT_PREFIX = "Server Error"
    APP_ERROR_EMAIL_SENDER = 'user@example.com'

    INSTALLED_APPS = [
        ...
        'error_tracker.DjangoErrorTracker'
    ]
    MIDDLEWARE = [
        ...
        'error_tracker.django.middleware.ExceptionTrackerMiddleWare'
    ]


Documentations
--------------
This has got extensive document browse at https://error-tracker.readthedocs.io/en/latest/

All docs are in `docs/source`

And if you want to preview any *.rst* snippets that you may want to contribute, go to `http://rst.ninjs.org/ <http://rst.ninjs.org/>`_.


Examples
--------
Several usage examples are included in the */tests* folder. Please feel free to add your own examples, or improve
on some of the existing ones, and then submit them via GitHub as a *pull-request*.

You can see some of these examples in action at https://github.com/sonus21/error-tracker/tree/master/examples
To run the examples on your local environment, one at a time, do something like::

    cd error-tracker/examples


Django::

     cd error-tracker/examples
     cd DjangoSample
     python manage.py runserver

Flask::

      cd flask-sample
      python app.py


Tests
-----
To run the tests, from the project directory, simply::

    pip install -r requirements-dev.txt
    bash tests/run-tests.sh

You should see output similar to::

    .............................................
    ----------------------------------------------------------------------
    Ran 31 tests in 1.144s

    OK


Contribution
-------------
You're most welcome to raise pull request or fixes.
