Autologging

1.3.2 · active · verified Wed Apr 15

Autologging (version 1.3.2) is a Python library that simplifies logging and tracing for classes and functions by eliminating boilerplate code. It provides decorators (`@logged` and `@traced`) to automatically inject a logger or trace method calls, respectively. It works with Python's standard `logging` module, allowing for independent configuration and control of application logging and program flow tracing. The library supports Python 2.7 and Python 3.3+.

Common errors

```
ModuleNotFoundError: No module named 'autologging'
```
cause The 'autologging' module is not installed in the Python environment.

fix Install the module using pip: 'pip install autologging'.
```
ImportError: cannot import name 'logged' from 'autologging'
```
cause The 'autologging' module is installed, but the 'logged' decorator cannot be imported, possibly due to an outdated version.

fix Ensure you have the latest version of autologging installed: 'pip install --upgrade autologging'.
```
AttributeError: module 'autologging' has no attribute 'traced'
```
cause The 'traced' decorator is not found in the 'autologging' module, likely due to an incorrect installation or version.

fix Verify the installation and version of autologging: 'pip show autologging'.
```
TypeError: 'NoneType' object is not callable
```
cause This error can occur if the 'traced' decorator is not properly applied, possibly due to incorrect usage or import issues.

fix Ensure that the 'traced' decorator is correctly imported and applied to the function or class.
```
ValueError: No JSON object could be decoded
```
cause This error may occur if the logging configuration is set to output in JSON format, but the log messages are not properly formatted.

fix Check the logging configuration and ensure that log messages are correctly formatted as JSON.

Warnings

gotcha When combining `@logged` and `@traced` decorators on the same class or function, it is recommended to apply `@traced` as the outermost decorator and `@logged` as the innermost (i.e., `@traced @logged def ...`). While the library is designed to work regardless of order, this order is considered 'safe' because `@logged` simply sets an attribute and returns the original object.
Fix: Always apply `@traced` before `@logged` on the same callable.
gotcha If a subclass of a `@logged`-decorated parent class wishes to use a `self.__log` object that correctly reflects its own class name in log messages, it must itself be decorated with `@logged`. Otherwise, logs made through the parent's `__log` will show the parent's name.
Fix: Decorate subclasses with `@logged` if they need their own `__log` instance and proper logger naming.
gotcha When using `autologging` with IronPython, you might encounter misreported line numbers and '<unknown file>' in log records due to IronPython's limited support for frames.
Fix: Be aware of these limitations when debugging on IronPython; this is a platform-specific issue.
gotcha Key names for extra data passed to Python's standard logging module (which autologging uses) cannot clash with some internal names (e.g., 'message', 'args'). If a clash occurs, autologging may issue a warning and change the key name (e.g., from 'message' to 'protected_message').
Fix: Avoid using Python logging's internal keyword arguments as keys in your extra logging data.

Install

pip install Autologging Install stable version

Imports

logged
```
from autologging import logged
```
traced
```
from autologging import traced
```
TRACE
```
from autologging import TRACE
```
A custom log level (value 1) for tracing, lower in severity than `logging.DEBUG`.

Quickstart

This example demonstrates how to use the `@logged` and `@traced` decorators on a class. It sets up basic logging to console, including the custom `TRACE` level. When `MyClass` methods are called, `__log` is available for manual logging, and `@traced` automatically logs method entry and exit. Ensure `logging.getLogger().setLevel(TRACE)` is called to make `TRACE` level messages visible.

import logging
import sys
from autologging import logged, traced, TRACE

# Configure basic logging to see the output
logging.basicConfig(
    level=logging.DEBUG,
    stream=sys.stdout,
    format="%(levelname)s:%(name)s:%(funcName)s:%(message)s"
)
# Set root logger level to TRACE to see tracing output
logging.getLogger().setLevel(TRACE)

@traced # Apply @traced outermost for consistent behavior
@logged
class MyClass:
    def __init__(self, name):
        self.name = name
        self.__log.info("MyClass instance created with name: %s", self.name)

    def do_work(self, value):
        self.__log.debug("Doing work with value: %s", value)
        result = value * 2
        return result

    def _internal_method(self):
        self.__log.trace("Executing internal method.")
        return "internal_result"

# Example usage
instance = MyClass("Example")
output = instance.do_work(10)
print(f"Result of do_work: {output}")
instance._internal_method()

view raw JSON →