Ideally, structlog should be able to be used as a drop-in replacement for standard library’s logging by wrapping it. In other words, you should be able to replace your call to logging.getLogger() by a call to structlog.get_logger() and things should keep working as before (if structlog is configured right, see Suggested Configuration below).
If you run into incompatibilities, it is a bug so please take the time to report it! If you’re a heavy logging user, your help to ensure a better compatibility would be highly appreciated!
To make structlog’s behavior less magicy, it ships with a standard library-specific wrapper class that has an explicit API instead of improvising: structlog.stdlib.BoundLogger. It behaves exactly like the generic structlog.BoundLogger except:
structlog comes with a few standard library-specific processors:
A basic configuration to output structured logs in JSON format looks like this:
import structlog
structlog.configure(
processors=[
structlog.stdlib.filter_by_level,
structlog.stdlib.add_logger_name,
structlog.stdlib.add_log_level,
structlog.stdlib.PositionalArgumentsFormatter(),
structlog.processors.TimeStamper(fmt='iso'),
structlog.processors.StackInfoRenderer(),
structlog.processors.format_exc_info,
structlog.processors.JSONRenderer()
],
context_class=dict,
logger_factory=structlog.stdlib.LoggerFactory(),
wrapper_class=structlog.stdlib.BoundLogger,
cache_logger_on_first_use=True,
)
To make your program behave like a proper 12 factor app that outputs only JSON to stdout, configure the logging module like this:
import logging
import sys
handler = logging.StreamHandler(sys.stdout)
root_logger = logging.getLogger()
root_logger.addHandler(handler)
If you plan to hook up the logging output to logstash, as suggested in Logging Best Practices, the simplest approach is to configure logstash-forwarder to pick up the output from your application. To achieve this, configure your process supervisor (such as runit or supervisord) to store the output in a file, and have logstash-forwarder monitor that file to ship it to the central log collection server. This approach also applies to other centralized logging solutions.