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 context managers, decorators, and via managed IndentLogger objects.

Examples

Context Manager

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

Decorator

from logindent import IndentLogger

logger = IndentLogger('my-logger')

@logger.block("Starting my task", "Completed my task")
def my_task():
    logger.debug("Running sub-task A")
    ...
    logger.debug("Running sub-task B")
    ...

my_task()

INFO  - Starting my task
DEBUG -     Running sub-task A
DEBUG -     Running sub-task B
INFO  - Completed my task

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 Indentation

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 logindent

Use logindent when you want a lightweight, text-based solution to make logs more human-readable. In particular, logindent 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 logindent.