Skip to main content

fw-logging

Logging helper library for standard logging configuration, JSON formatting, and for tailing (non-)structured logs re-formatted and colorized for humans.

Installation

pip install fw-logging

Usage

logformat

Use the CLI utility logformat to re-format (Flywheel) logs for humans:

# pipe json and/or text logs directly
kubectl logs my-pod | logformat
# OR pass a filename containing the same
kubectl logs my-pod > my-pod.log
logformat my-pod.log
# OR pass a rich text file (.rtf) of logs
logformat my-pod-log.rtf

Library

Use the fw_logging module to set up python logging in 2 lines:

import fw_logging
fw_logging.setup_logging()

The default configuration sets up logging at level INFO to stdout, formatted as text with colorized levels and caller information.

To emit structured JSON logs in production just override the formatter using an environment variable: FW_LOG_FORMATTER=json.

Logging

setup_logging() configures the logging root logger, so emit records with the standard library as usual - fw_logging is only needed for the setup itself, and 3rd party library logs get the same treatment:

import logging

log = logging.getLogger(__name__)
log.info("processing %d files", 5)
# 2024-01-01T00:00:00.000 INFO my.module processing 5 files

try:
    raise ValueError("invalid")
except ValueError:
    log.exception("processing failed")
# 2024-01-01T00:00:00.000 ERRO my.module processing failed
# Traceback (most recent call last):
#   ...
# ValueError: invalid

To add key-value pairs to a single record only, pass them via the stdlib extra kwarg as context (or use the context logger below to set them once):

log.info("job finished", extra={"context": {"job": "123"}})
# 2024-01-01T00:00:00.000 INFO my.module job finished; job=123

The json formatter also picks up extra={"tag": "..."} on a record, which overrides the json_tag config option for that one log.

Configuration

Pass any config option to setup_logging() as a kwarg to set the application defaults, and override them at runtime with the FW_LOG_-prefixed envvars:

fw_logging.setup_logging(
    level="DEBUG",
    handler="stderr",
    loggers={"pika": "ERROR", "urllib3": None},
    filters={"health": {"msg": r"GET /healthz"}},
)

Kwargs take precedence over the envvars, except for loggers and filters, where the two are merged with the env-configured entries winning. A logger with a None level is pinned to the root logger's level, and filters exclude records by logger name prefix and/or msg regex.

Table of all config options and the corresponding envvars:

Option Envvar Default Example / Note
level FW_LOG_LEVEL INFO DEBUG
handler FW_LOG_HANDLER stdout stderr / file
formatter FW_LOG_FORMATTER text json
loggers FW_LOG_LOGGERS {"pika":"ERROR"}
filters FW_LOG_FILTERS {"a":{"msg":"rgx"}}
filename FW_LOG_FILENAME log.txt file handler only
max_bytes FW_LOG_MAX_BYTES 10485760 rotate at 10 MB
backup_count FW_LOG_BACKUP_COUNT 10 rotated files kept
fmt FW_LOG_FMT {}-style text fmt
datefmt FW_LOG_DATEFMT %Y-%m-%dT%H:%M:%S
callfmt FW_LOG_CALLFMT caller as mod:lineno
color FW_LOG_COLOR default: auto (tty)
json_tag FW_LOG_JSON_TAG json formatter only
json_process FW_LOG_JSON_PROCESS false add the process id
json_thread FW_LOG_JSON_THREAD false add the thread id

Use get_log_config() with the same kwargs to get the logging.config dictConfig without applying it, and Filter as a context manager to exclude records temporarily:

with fw_logging.Filter(msg="expected noise"):
    noisy_function()

Context

Use get_context_logger() to attach context key-value pairs to every record:

import fw_logging
fw_logging.setup_logging()

log = fw_logging.get_context_logger(__name__, app="my-app")
log.info("starting")
# 2024-01-01T00:00:00.000 INFO my.module starting; app=my-app

job_log = log.with_context(job="123")
job_log.info("running")
# 2024-01-01T00:00:00.000 INFO my.module running; app=my-app; job=123

with_context() returns a new logger, leaving the original untouched. The text formatter appends the context as ; key=value pairs, while the json formatter adds the keys to the record itself (without clobbering fixed fields like message or severity), keeping them queryable in log aggregators.

License

MIT

Metadata

Release files for fw-logging 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for fw-logging 3.0.0
File Interpreter ABI Platform Actions
fw_logging-3.0.0-py3-none-any.whl Python 3 none any Details for fw_logging-3.0.0-py3-none-any.whl

Release files / fw_logging-3.0.0-py3-none-any.whl

Download URL fw_logging-3.0.0-py3-none-any.whl
Size 11.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a33bacfa9a53153b95ad713155b0fd4a99bf208d39e63ee51aad2694f2fc3582
BLAKE2b-256 checksum
How to use checksums
2c0c26a98805d2c54395d6ae3654cf08dc10a621674ce798d68c38a7400f883a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Alpine Linux","version":"3.25.0_alpha20260805","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for fw-logging 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page