Processors, Formatters & Handlers¶

Processors live in plainlog.processors:

• Processors transform a log record in the Core's background thread.
• Formatters are processors that render a record into a string, stored in record["formatted_message"].
• Handlers are processors that perform output.

But overall they are simply processors with the same interface. Naming is just there to clarify what they do.

Every processor is a callable with the signature __call__(record: Record) -> Record and may optionally provide a close() method for cleanup:

• __call__(record: Record) -> Record — runs in the Core's background thread after dequeueing. This is where I/O happens. Return an empty dict {} to stop processing for that record.
• close() — cleanup resources (close files, wait for futures, etc.). Optional.

Processors are configured as a Sequence and run in order. A typical setup is a formatter followed by a handler:

from plainlog import configure_log
from plainlog.processors import SimpleFormatter, Stream

configure_log(processors=[SimpleFormatter(), Stream()])

Built-in Processors¶

Formatters¶

Output Handlers¶

Composition Handlers¶

Filters, Helpers & Utilities¶

All of these are available from plainlog.processors.

Usage¶

Formatter and Stream¶

from plainlog import configure_log
from plainlog.processors import JsonFormatter, Stream

configure_log(processors=[JsonFormatter(), Stream()])

FingersCrossed — Buffer Until Error¶

from plainlog import configure_log
from plainlog.processors import FingersCrossed, SimpleFormatter, Stream

# Buffer up to 100 records, flush everything on ERROR (level 40)
handler = FingersCrossed(
    Stream(),
    action_level=40,
    buffer_size=100,
)
configure_log(processors=[SimpleFormatter(), handler])

AsyncBridge Subclass¶

import asyncio
from plainlog.processors import AsyncBridge

class MyAsyncBridge(AsyncBridge):
    async def write(self, message):
        # e.g. send to a network sink
        await asyncio.sleep(0)
        print(message)

Redacting Sensitive Fields¶

redact_fields matches exact key names; redact_by_pattern matches any key containing a given substring. Both are case-insensitive and recurse through nested dicts and lists, including dicts inside lists. Matching applies to leaf values: when a matched key holds a container, the processor descends into it and masks matching leaves instead of replacing the container. Place them early in the pipeline, before any formatter, so formatted/serialized output never contains the raw value. They scrub matching keys anywhere in the record — at the top level and inside nested containers. Secrets interpolated directly into the message string (e.g. log.info(f"password={pw}")) are not caught.

import sys
from plainlog import configure_log, logger
from plainlog.processors import (
    ConsoleRenderer,
    Stream,
    redact_by_pattern,
)

configure_log(
    processors=[
        redact_by_pattern("password", "token", "secret", "api_key"),
        ConsoleRenderer(colors=False),
        Stream(sys.stdout),
    ]
)

log = logger.new()
log.info("login attempt", username="alice", password="hunter2")
# -> ... username=alice password=***REDACTED***  (field order may vary)

API Reference¶

Stream¶

SubProcessor¶

from plainlog.processors import Stream, SubProcessor, format_message

handler = SubProcessor([format_message, Stream()])

WrapStandardHandler¶

FingersCrossed¶

FileWriter¶

AsyncBridge¶

SimpleFormatter¶

JsonFormatter¶

ConsoleRenderer¶

FilterList¶

WhitelistLevel¶

Helper functions¶