logindent

Lightweight utility class for structurally indenting log messages.

About

Indenting log messages is a simple way to make log messages more human readable. In particular, indenting can help distinguish messages for high-level tasks from messages for their subtasks. For example, in the following indented log:

Starting task 1
    Running step 1
    Running step 2
    Running step 3
Completed task
Starting a second task
    Querying server
    Parsing response
    Updating database
Completed second task

it is immediately clear where tasks 1 and 2 begin, and which sub-steps belong to each task.

The logindent package provides the lightweight IndentLogger class to help implement this functionality. The class provides routines to track indenting levels and record log messages to standard logging streams. When logging messages, the correct amount of indentation will be prepended to the log message automatically. Users can manage the indentation level using either context blocks, or via managed IndentLogger objects.

Examples

Indented logging using context blocks:

from logindent import IndentLogger

logger = IndentLogger("my-logger")
logger.info("Starting task 1")
with logger.indent():
    logger.debug("Running step 1")
    logger.debug("Running step 2")
    logger.debug("Running step 3")
    with logger.indent():
        logger.debug("Ran sub-step A")
        logger.debug("Ran sub-step B")
logger.info("Completed task 1")

INFO  - Starting task 1
DEBUG -     Running step 1
DEBUG -     Running step 2
DEBUG -     Running step 3
DEBUG -         Ran sub-step A
DEBUG -         Ran sub-step B
INFO  - Completed task 1

Indented logging using managed loggers:

logger.info("Starting task 1")

task_logger = logger.indented()
task_logger.debug("Running step 1")
task_logger.debug("Running step 2")
task_logger.debug("Running step 3")

step3_logger = task_logger.indented()
step3_logger.debug("Ran sub-step A")
step3_logger.debug("Ran sub-step B")

logger.info("Completed task 1")

INFO  - Starting task 1
DEBUG -     Running step 1
DEBUG -     Running step 2
DEBUG -     Running step 3
DEBUG -         Ran sub-step A
DEBUG -         Ran sub-step B
INFO  - Completed task 1

Customize indent level and string:

logger = IndentLogger('my-logger', indent_level=2, indent_string="..")

logger.info("Starting task 1 in some running process")
with logger.indent():
    logger.debug("Running step 1")
    logger.debug("Running step 2")
    logger.debug("Running step 3")

INFO  - ....Starting task 1 in some running process
DEBUG - ......Running step 1
DEBUG - ......Running step 2
DEBUG - ......Running step 3

When to use IndentLogger

The IndentLogger class is best used when you want a lightweight, text-based solution to make logs more human-readable. In particular, IndentLogger works well for both console and file logs. By contrast, other solutions for human-readable logs (such as colorized messages or rich trees) can sometimes render poorly when logged to file.

Finally, if you want logs that are machine readable (rather than human readable), then consider using structured logging instead of IndentLogger.