Console Output#

To make development a more pleasurable experience, structlog comes with the structlog.dev module.

The highlight is structlog.dev.ConsoleRenderer that offers nicely aligned and colorful[1] console output.

If either of the Rich or better-exceptions packages is installed, it will also pretty-print exceptions with helpful contextual data. Rich takes precedence over better-exceptions, but you can configure it by passing structlog.dev.plain_traceback() or structlog.dev.better_traceback() for the exception_formatter parameter of ConsoleRenderer.

The following output is rendered using Rich:

_images/console_renderer.png

Colorful console output by ConsoleRenderer.#

You can find the code for the output above in the repo.

To use it, just add it as a renderer to your processor chain. It will recognize logger names, log levels, time stamps, stack infos, and exc_info as produced by structlog’s processors and render them in special ways.

Warning

For pretty exceptions to work, format_exc_info() must be absent from the processors chain.

structlog’s default configuration already uses ConsoleRenderer, therefore if you want nice colorful output on the console, you don’t have to do anything except installing Rich or better-exceptions (and Colorama on Windows). If you want to use it along with standard library logging, we suggest the following configuration:

import structlog

structlog.configure(
    processors=[
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M.%S"),
        structlog.processors.StackInfoRenderer(),
        structlog.dev.ConsoleRenderer()  # <===
    ],
    context_class=dict,
    logger_factory=structlog.stdlib.LoggerFactory(),
    wrapper_class=structlog.stdlib.BoundLogger,
    cache_logger_on_first_use=True,
)

Standard Environment Variables#

structlog’s default configuration uses colors if standard out is a TTY (i.e. an interactive session).

It’s possible to override this behavior by setting two standard environment variables to any value except an empty string:

  • FORCE_COLOR activates colors, regardless of where output is going.

  • NO_COLOR disables colors, regardless of where the output is going and regardless the value of FORCE_COLOR. Please note that NO_COLOR disables all styling, including bold and italics.

Disabling Exception Pretty-Printing#

If you prefer the default terse Exception rendering, but still want Rich installed, you can disable the pretty-printing by instantiating structlog.dev.ConsoleRenderer() yourself and passing exception_formatter=structlog.dev.plain_traceback.