Welcome to Django-Analog’s documentation!

Contents:

Configuration

Analog has two settings configurable in your project’s Django settings:

ANALOG_KINDS

You can use this to add custom log entry kinds. Kind _mnemonics_ are what you might usually pass to add_log_entry(); short, understandable names for the log entry kind. These are mapped to integers on the database level.

Note

It’s a good idea to “namespace” your custom log entry kinds by starting them at some arbitrary value, as in the example below. In particular, kinds from 0 to 10 are “reserved” by Analog itself. However, if you really feel like it, there’s nothing stopping you from reassigning those kinds too.

For example, an application hell-bent on logging different kinds of food might declare custom log entry kinds like this.

_KIND_BASE = 0x10000
ANALOG_KINDS = {
  "hamburger": _KIND_BASE + 1,
  "tortilla": _KIND_BASE + 2
}

ANALOG_KIND_LABELS

This dictionary represents the human-readable, likely localizable labels for the custom log kinds declared in ANALOG_KINDS.

Declaring labels is optional – the mnemonic will be substituted instead if you don’t declare them – but it’s definitely good sportsmanship.

Note

For your localization convenience, any bare strings here will be converted to Django’s ugettext_lazy instances.

ANALOG_KIND_LABELS = {
  "hamburger": "hämmbörger",
  "tortilla": "delicious tortilla"
}

API

analog.define_log_model(model_class, base_class=<class 'analog.models.BaseLogEntry'>, on_delete=<function CASCADE>)

Define a log model for a given Django model class (“parent model”).

The log entry model class is returned, and it must be assigned to a variable in a models.py file to allow Django to pick it up for migrations.

For all intents and purposes, the log entry model is owned by your app after this function creates it.

The parent model is anointed with two new attributes:

  • add_log_entry, a function to add a log entry. (See BaseLogEntry.add_log_entry() for details, but heed the fact that the target argument will be implicitly passed.)
  • log_model, a reference to the log entry model.
Parameters:
  • model_class – The model class this log entry model is for.
  • base_class – Replacement base class for the model. Should be compatible with BaseLogEntry never- theless.
  • on_delete – The on_delete clause for the log entry class’s foreign key. Defaults to CASCADE, i.e. that log entries are deleted when the logged model instance is. PROTECT would be another sane option.
Returns:

The log entry model.
class analog.BaseLogEntry(*args, **kwargs)

Abstract base model class for the various log models.

The concrete models are created by define_log_model().

classmethod add_log_entry(target, message, identifier=None, kind=u'other', user=None, extra=None, save=True)

Add a log entry.

Note

This method should not be used directly; instead, the same method, aside from the target argument, is available on models that have been anointed by define_log_model().

Parameters:
  • target – Target model instance
  • message (str) – Log message
  • identifier (str|None) – Log message identifier. Useful for tagging log entries in a way that is not necessarily human-readable.
  • kind (int|str) – Log entry kind. Either a mnemonic string (preferred and readable), or the actual entry ID integer (if you really have to). Kinds are configured in your project’s settings.
  • user – An optional user object (an instance of settings.AUTH_USER_MODEL) to attach to this log entry.
  • extra (object|None) – Extra data, if applicable. If set, this must be serializable to JSON; ``dict``s are a good idea.
  • save (bool) – Whether to immediately save the log entry. Default True.
Returns:

The created log entry
get_kind_display()

Get the kind label for this log entry.

This emulates the behavior Django would have for fields that have the choices kwarg.

Indices and tables