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

# structlog

Simple. Powerful. Fast. Pick three.

Release 25.3.0 (What’s new?)

structlog is the production-ready logging solution for Python:

- Simple: Everything is about functions that take and return dictionaries – all hidden behind familiar APIs.

- Powerful: Functions and dictionaries aren’t just simple but also powerful. structlog leaves you in control.

- Fast: structlog is not hamstrung by designs of yore. Its flexibility comes not at the price of performance.

Thanks to its flexible design, you choose whether you want structlog to take care of the output of your log entries or whether you prefer to forward them to an existing logging system like the standard library’s `logging` module.

The output format is just as flexible and structlog comes with support for JSON, logfmt, as well as pretty console output out-of-the-box:

## Sponsors

structlog would not be possible without our amazing sponsors. Especially those generously supporting us at the The Organization tier and higher:

Please consider joining them to help make structlog’s maintenance more sustainable!

## Introduction

structlog has been successfully used in production at every scale since 2013, while embracing cutting-edge technologies like asyncio, context variables, or type hints as they emerged. Its paradigms proved influential enough to help design structured logging packages across ecosystems.

If you’d like more information on why structured logging in general – and structlog in particular – are good ideas, we’ve prepared a summary just for you.

Otherwise, let’s dive right in!

## Basics

The first chapters teach you all you need to use structlog productively. They build gently on each other, so ideally, read them in order. If anything seems confusing, don’t hesitate to have a look at our Glossary!

Basics

- Getting Started
  - Installation
  - Your first log entry
  - Building a context
  - Manipulating log entries in flight
  - Rendering
  - structlog and standard library’s `logging`
  - asyncio
  - Liked what you saw?
- Bound Loggers
  - Context
  - Output
  - Filtering by log levels
  - Wrapping loggers manually
- Configuration
  - What to configure
- Processors
  - Chains
  - Filtering
  - Adapting and rendering
  - Third-Party packages
- Context Variables
  - Support for `contextvars.Token`
  - Example: Flask and thread-local data
- Exceptions
  - Transformations
  - Console rendering

## Development affordances

structlog’s focus is on production systems, but it comes with pretty console logging and handy in-development helpers both for your comfort and your code’s quality.

Development Affordances

- Console Output
  - Console output configuration
  - Standard environment variables
  - Disabling exception pretty-printing
- Testing
- Type Hints

## Integration with existing systems

structlog is both zero-config as well as highly configurable. You can use it on its own or integrate with existing systems. Dedicated support for the standard library and Twisted is shipped out-of-the-box.

Integrations

- Frameworks
  - Celery
  - Django
  - Flask
  - Litestar
  - OpenTelemetry
  - Pyramid
  - Twisted
- Standard Library Logging
  - Just enough `logging`
  - Concrete bound logger
  - Processors
  - Suggested configurations
- Twisted
  - Concrete bound logger
  - Processors
  - Bending foreign logging to your will
  - Suggested configuration

## structlog in practice

The following chapters deal with considerations of using structlog in the real world.

In Practice

- Recipes
  - Renaming the `event` key
  - Fine-grained log-level filtering
  - Custom wrappers
  - Passing context to worker threads
  - Switching console output to standard error
- Logging Best Practices
  - Canonical log lines
  - Pretty printing vs. structured output
  - Centralized logging
- Performance
  - Example

## Reference

Reference

- API Reference
  - `structlog` Package
  - `structlog.dev` Module
  - `structlog.testing` Module
  - `structlog.contextvars` Module
  - `structlog.threadlocal` Module
  - `structlog.processors` Module
  - `structlog.stdlib` Module
  - `structlog.tracebacks` Module
  - `structlog.typing` Module
  - `structlog.twisted` Module
- Glossary
- Index
- Module Index

## Deprecated features

Deprecated Features

- Legacy Thread-local Context