Metadata-Version: 2.1
Name: django-eventlog
Version: 1.5
Summary: django-eventlog stores event messages in a Django model.
Home-page: https://github.com/bartTC/django-eventlog
Author: Martin Mahner
Author-email: martin@mahner.org
License: MIT
Keywords: django,logging,logger,events
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Django
Requires-Python: >=3.8
License-File: LICENSE
Requires-Dist: django>=3.2

.. image:: https://img.shields.io/pypi/v/django-eventlog.svg
    :target: https://pypi.org/project/django-eventlog/

.. image:: https://github.com/bartTC/django-eventlog/actions/workflows/push.yml/badge.svg
    :target: https://github.com/bartTC/django-eventlog/actions/workflows/push.yml

-----

📖 **Full documentation: https://django-eventlog.readthedocs.io/**

*Compatibility Matrix:*

========= === === ==== ==== ====
Py/Dj     3.8 3.9 3.10 3.11 3.12
========= === === ==== ==== ====
3.2 (LTS)  ✓   ✓   ✓    ✓    ✓
4.0        ✓   ✓   ✓    ✓    ✓
4.1        ✓   ✓   ✓    ✓    ✓
4.2 (LTS)  ✓   ✓   ✓    ✓    ✓
5.0        —   —   ✓    ✓    ✓
========= === === ==== ==== ====

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

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:

.. code-block:: python

    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')


You can reuse an event group by specifying a group name and attach optional data.
Data must be JSON serializable.

.. code-block:: python

    from eventlog import EventGroup

    def purchase():
        e = EventGroup(group_id=f"Order {self.order.pk}")
        e.info("Sent order to Shopify", data={"items": [1, 2, 3]})

    def subscribe_newsletter():
        e = EventGroup(group_id=f"Order {self.order.pk}")
        e.info("User subscribed to newsletter on checkout", data={"email": "user@example.com"})


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/main/docs/_static/change_list.png
   :scale: 100 %

The details view of an event will list all other events of this group so you
can track the progress:

.. image:: https://github.com/bartTC/django-eventlog/raw/main/docs/_static/change_form.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.

=========
Changelog
=========

1.5 (wip)
=========

- Event can have optional, JSON serializable data attached.
- Fixed dark mode colors.
- Various Admin UI improvements.

1.4 (2024-03-05)
================

- Event groups can now have arbitrary names instead of UUIDs.
- Event comments is a textfield.
- Fixed potential migration warnings around AutoFields.

1.3 (2023-10-04)
================

- Python 3.12 compatibility
- Django 5.0 support
- Type Annotations

1.2 (2023-04-28)
================

- Python 3.7 to 3.11 compatibility
- Django 3.2 to 4.2 support

1.1 (2018-05-11)
================

- Added ability to manually set a group id to make an EventGroup object
  reusable through threads.

1.0 (2018-02-13)
================

- Production ready 1.0 release.
- The details Admin view now displays all events of the group with an
  annotated delay, so you can see the progress of the group.

0.9 (2018-02-13)
================

- Initial release.
- Django 1.8 to 2.0 compatibility.
- Python 2.7 to 3.6 compatibility.

