Show HN: Python Logfmter 

A Python package which supports global logfmt formatted logging.

Install

Usage

Before integrating this library, you should be familiar with Python’s logging
functionality. I recommend reading the Basic Logging
Tutorial.

This package exposes a single Logfmter class that can be integrated into
the standard library logging system similar to any logging.Formatter.

The provided formatter will logfmt encode all logs. Key value pairs are provided
via the extra keyword argument or by passing a dictionary as the log message.

Basic

import logging
from logfmter import Logfmter

handler = logging.StreamHandler()
handler.setFormatter(Logfmter())

logging.basicConfig(handlers=[handler])

logging.error("hello", extra={"alpha": 1}) # at=ERROR msg=hello alpha=1
logging.error({"token": "Hello, World!"}) # at=ERROR token="Hello, World!"

Default Keys

You can request that the formatter always include certain attributes on the
log record by using the keys parameter. If the key you want to include in
your output is represented by a different attribute on the log record, then
you can use the mapping parameter to provide that key/attribute mapping.

Notice, the keys parameter defaults to ["at"] and will be overridden
by any provided keys.

import logging
from logfmter import Logfmter

formatter = Logfmter(keys=["at", "processName"])

handler = logging.StreamHandler()
handler.setFormatter(formatter)

logging.basicConfig(handlers=[handler])

logging.error("hello") # at=ERROR processName=MainProceess msg=hello

Utilizing a mapping to convert the processName attribute to process.

Notice, the mapping parameter defaults to {"at": "levelname"} and will be overridden
by any provided mapping.

import logging
from logfmter import Logfmter

formatter = Logfmter(
    keys=["at", "process"],
    mapping={"at": "levelname", "process": "processName"}
)

handler = logging.StreamHandler()
handler.setFormatter(formatter)

logging.basicConfig(handlers=[handler])

logging.error("hello") # at=ERROR process=MainProceess msg=hello

Date Formatting

If you request the asctime attribute (directly or through a mapping), then the date format
can be overridden through the datefmt parameter.

import logging
from logfmter import Logfmter

formatter = Logfmter(
    keys=["at", "when"],
    mapping={"at": "levelname", "when": "asctime"},
    datefmt="%Y-%m-%d"
)

handler = logging.StreamHandler()
handler.setFormatter(formatter)

logging.basicConfig(handlers=[handler])

logging.error("hello") # at=ERROR when=2022-04-20 msg=hello

Customize

You can subclass the formatter to change its behavior.

import logging
from logfmter import Logfmter


class CustomLogfmter(Logfmter):
    """
    Provide a custom logfmt formatter which formats
    booleans as "yes" or "no" strings.
    """

    @classmethod
    def format_value(cls, value):
        if isinstance(value, bool):
            return "yes" if value else "no"

	return super().format_value(value)

handler = logging.StreamHandler()
handler.setFormatter(CustomLogfmter())

logging.basicConfig(handlers=[handler])

logging.error({"example": True}) # at=ERROR example=yes

Development

Required Software

Refer to the links provided below to install these development dependencies:

• direnv
• git
• pyenv

Getting Started

Setup

$ runtimes.txt xargs -n 1 pyenv install -s
$ direnv allow
$ pip install -r requirements/dev.txt
$ pre-commit install
$ pip install -e .

Tests

Run the test suite against the active python environment.

Run the test suite against the active python environment and
watch the codebase for any changes.

Run the test suite against all supported python versions.

Publishing

Create

1. Update the version number in logfmter/__init__.py.

2. Add an entry in HISTORY.md.

3. Commit the changes, tag the commit, and push the tags:

   ..”
   $ git tag v.. $ git push origin main –tags”>

   $ git commit -am "v.."
   $ git tag vmajor>.minor>.patch>
   $ git push origin main --tags

4. Convert the tag to a release in GitHub with the history
   entry as the description.

Build

Upload