Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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:

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, there’s the `structlog.stdlib.recreate_defaults()` helper.

See also

Exceptions for more information on how to configure exception rendering. For the console and beyond.

## Console output configuration

Added in version 23.3.0.

You can freely configure how the key-value pairs are formatted: colors, order, and how values are stringified.

For that `ConsoleRenderer` accepts the columns parameter that takes a list of `Column`s. It allows you to assign a formatter to each key and a default formatter for the rest (by passing an empty key name). The order of the column definitions is the order in which the columns are rendered; the rest is – depending on the sort_keys argument to `ConsoleRenderer` – either sorted alphabetically or in the order of the keys in the event dictionary.

You can use a column definition to drop a key-value pair from the output by returning an empty string from the formatter.

When the API talks about “styles”, it means ANSI control strings. You can find them, for example, in Colorama.

It’s best demonstrated by an example:

    import structlog
    import colorama

    cr = structlog.dev.ConsoleRenderer(
        columns=[
            # Render the timestamp without the key name in yellow.
            structlog.dev.Column(
                "timestamp",
                structlog.dev.KeyValueColumnFormatter(
                    key_style=None,
                    value_style=colorama.Fore.YELLOW,
                    reset_style=colorama.Style.RESET_ALL,
                    value_repr=str,
                ),
            ),
            # Render the event without the key name in bright magenta.
            structlog.dev.Column(
                "event",
                structlog.dev.KeyValueColumnFormatter(
                    key_style=None,
                    value_style=colorama.Style.BRIGHT + colorama.Fore.MAGENTA,
                    reset_style=colorama.Style.RESET_ALL,
                    value_repr=str,
                ),
            ),
            # Default formatter for all keys not explicitly mentioned. The key is
            # cyan, the value is green.
            structlog.dev.Column(
                "",
                structlog.dev.KeyValueColumnFormatter(
                    key_style=colorama.Fore.CYAN,
                    value_style=colorama.Fore.GREEN,
                    reset_style=colorama.Style.RESET_ALL,
                    value_repr=str,
                ),
            ),
        ]
    )

    structlog.configure(processors=structlog.get_config()["processors"][:-1]+[cr])

Hint

You can replace only the last processor using:

    structlog.configure(processors=structlog.get_config()["processors"][:-1]+[cr])

## Standard environment variables

structlog’s default configuration uses colors if standard out is a TTY (that is, 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`.

[1]

Requires the Colorama package on Windows.