.. _index:

===============
django-eventlog
===============

.. toctree::
   :maxdepth: 1

   installation
   settings
   testing

django-eventlog is a very simple event logger you can use to track certain
actions in your code. Events are stored in a Django model and can be viewed
in the Django Admin.

Usage Example::

    from eventlog import EventGroup

    e = EventGroup()                       # Start a new Event Group
    e.info('About to send 1000 mails.',    # Trigger an Event
           initiator='Mailer Daemon')
    try:
        # ... sending 1000 mails
        e.info('All emails sent!',         # Trigger an Event in the same group,
               initiator='Mailer Daemon')  # so they are combined in the admin.
    except Exception:
        e.error('There was an error sending the emails.',
                initiator='Mailer Daemon')


Events can be grouped in a "Event Group" and when hovering over one item
in the admin, all events of the same group are highlighted.

.. image:: https://github.com/bartTC/django-eventlog/raw/master/docs/_static/screenshot.png
   :scale: 100 %

.. note::
    While looking similar, it's not intended to be a replacement for your
    regular Python ``logging`` facility, rather an addition to it.

    django-eventlog stores it's data in a regular database model, so each log entry
    will trigger a SQL Insert. Therefore you should be careful using it in high
    performance and/or high volume environments.

