Autologging — easier logging and tracing for Python classes

Release:1.3.2
PyPI version Python version Python implementation License Wheel availability

Autologging eliminates boilerplate logging setup code and tracing code, and provides a means to separate application logging from program flow and data tracing.

Python modules that make use of Autologging are cleaner, leaner, and more resilient to changes that would otherwise require updating tracing statements.

Autologging allows for tracing to be configured (and controlled) independently from application logging. Toggle tracing on/off, write trace log records to a separate log, and use different formatting for trace log entries - all via standard Python logging facilities, and without affecting your application logging.

Python 2.7 and Python 3.4+ are supported using the same codebase. All examples given on this site use Python 3 syntax.

Autologging exposes two decorators (autologging.logged, autologging.traced) and a custom log level (autologging.TRACE).

A brief example:

 1 import logging
 2 import sys
 3
 4 from autologging import logged, TRACE, traced
 5
 6 @traced
 7 @logged
 8 class Example:
 9
10     def __init__(self):
11         self.__log.info("initialized")
12
13     def backwards(self, *words):
14         for word in words:
15             yield "".join(reversed(word))
16
17
18 if __name__ == "__main__":
19     logging.basicConfig(
20             level=TRACE, stream=sys.stderr,
21             format="%(levelname)s:%(filename)s,%(lineno)d:%(name)s.%(funcName)s:%(message)s")
22     example = Example()
23     for result in example.backwards("spam", "eggs"):
24         print(result)

Logging and tracing output:

$ python example.py
TRACE:example.py,10:__main__.Example.__init__:CALL *() **{}
INFO:example.py,11:__main__.Example.__init__:initialized
TRACE:example.py,10:__main__.Example.__init__:RETURN None
TRACE:example.py,13:__main__.Example.backwards:CALL *('spam', 'eggs') **{}
TRACE:example.py,13:__main__.Example.backwards:RETURN <generator object backwards at 0x7f50bdaf16e0>
TRACE:example.py,15:__main__.Example.backwards:YIELD <generator object backwards at 0x7f50bdaf16e0> 'maps'
maps
TRACE:example.py,15:__main__.Example.backwards:YIELD <generator object backwards at 0x7f50bdaf16e0> 'sgge'
sgge
TRACE:example.py,13:__main__.Example.backwards:STOP <generator object backwards at 0x7f50bdaf16e0>

New in version 1.0.1: Autologging is now officially tested and working under Jython, IronPython, PyPy, and Stackless Python.

New in version 1.1.0: Autologging now exposes the autologging.install_traced_noop function. This function replaces the traced decorator with a no-op that returns traced classes and functions unmodified (effectively disabling all tracing capabilities). This is useful for cases where any overhead from tracing is not desired (for example, when running in production environments, or when running performance tests).

New in version 1.2.0: Generator iterators now emit YIELD/STOP trace logging records (in addition to the CALL/RETURN tracing of the generator function itself).

New in version 1.3.2: Full tracing of generator iterators is now implemented. Autologging emits YIELD, SEND, THROW, CLOSE and STOP trace logging records as appropriate. Additionally, the repr of the generator iterator is now included in each log record for easier identification (can be compared to the generator function’s RETURN log record).

Download and Install

The easiest way to install Autologging is to use pip:

$ pip install Autologging

To install from source, clone the GitHub repository:

$ git clone https://github.com/mzipay/Autologging.git

Alternatively, download and extract a source .zip or .tar.gz archive from https://github.com/mzipay/Autologging/releases or https://pypi.python.org/pypi/Autologging.

Run the test suite and install the autologging module (make sure you have setuptools installed!):

$ cd Autologging
$ python setup.py test
$ python setup.py install

You can also install from one of the available binary packages available at https://pypi.python.org/pypi/Autologging or https://sourceforge.net/projects/autologging/files/.

Indices and tables