Skip to content

Home

What is it?

STandard STructured LOG (stlog) is Python 3.7+ structured logging library:

  • built on standard python logging and contextvars
  • very easy to configure with "good/opinionated" default values
  • which produces great output for both humans and machines
  • which believes in Twelve-Factor App principles about config and logs
  • dependency free (but can use fancy stuff (colors, augmented traceback...) from the rich library (if installed))

Features

  • standard, standard, standard: all stlog objects are built on standard python logging and are compatible with:
    • other existing handlers, formatters...
    • libraries which are using a standard logger (and stlog can automatically reinject the global context in log records produced by these libraries)
  • easy shorcuts to configure your logging
  • provides nice outputs for humans AND for machines (you can produce both at the same time)
  • structured with 4 levels of context you can choose or combine:
    • a global one set by environment variables (read at process start)
    • a kind of global one (thanks to contextvars)
    • a context linked to the logger object itself (defined during its building)
    • a context linked to the log message itself
  • a lot of configuration you can do with environment variables (in the spirit of Twelve-Factor App principles)

Non-Features

  • "A twelve-factor app never concerns itself with routing or storage of its output stream."
    • we are going to make an exception on this for log files (see roadmap)
    • but we don't want to introduce complex/network outputs like syslog, elasticsearch, loki...
  • standard, standard, standard: we do not want to move away from standard python logging compatibility

What is structured logging?

Structured logging is a technique used in software development to produce log messages that are more easily parsed and analyzed by machines. Unlike traditional logging, which typically consists of free-form text messages, structured logging uses a well-defined format that includes named fields with specific data types.

The benefits of structured logging are many. By using a standard format, it becomes easier to automate the processing and analysis of logs. This can help with tasks like troubleshooting issues, identifying patterns, and monitoring system performance. It can also make it easier to integrate logs with other systems, such as monitoring and alerting tools.

Some common formats for structured logging include JSON, XML, and key-value pairs. In each case, the format includes a set of fields that provide information about the log message, such as the severity level, timestamp, source of the message, and any relevant metadata.

Structured logging is becoming increasingly popular as more developers recognize its benefits. Many logging frameworks and libraries now include support for structured logging, making it easier for developers to adopt the technique in their own projects.

(thanks to ChatGPT)

Roadmap

  • add file outputs
  • add a full logfmt formatter
  • more configuration (outputs) by env