rfd-logging

Standardised JSON logging for RFD services. One line per entry, machine-parseable, zero dependencies.

Installation

From PyPI:

pip install rfd-logging

Editable local install (for RFD services):

uv add --editable C:\Github\RFD_Logging

Usage

from rfd_logging import get_logger

logger = get_logger("rfd-collectors", log_dir="logs")

# Basic info
logger.info("Service started")

# With extra fields
logger.info("Request received", extra={"endpoint": "/api/data", "request_id": "req-abc123"})

# Error with description
logger.error("Database unreachable", extra={"error": "Connection refused", "host": "db.local"})

# Exception with traceback
try:
    1 / 0
except ZeroDivisionError:
    logger.exception("Unhandled error during processing")

Sample JSON output

{"timestamp": "2026-06-21T20:38:33.092Z", "level": "INFO", "service": "rfd-collectors", "message": "Request received", "extra": {"endpoint": "/api/data"}, "request_id": "req-abc123"}
{"timestamp": "2026-06-21T20:38:33.105Z", "level": "ERROR", "service": "rfd-collectors", "message": "Database unreachable", "extra": {"host": "db.local"}, "request_id": null, "error": "Connection refused"}
{"timestamp": "2026-06-21T20:38:33.110Z", "level": "ERROR", "service": "rfd-collectors", "message": "Unhandled error during processing", "extra": {}, "request_id": null, "traceback": "Traceback (most recent call last):\n  ..."}

Output fields

Configuration

Log level

Set via environment variable before starting the service:

set RFD_LOG_LEVEL=DEBUG   # Windows
export RFD_LOG_LEVEL=DEBUG  # Linux/macOS

Default: INFO. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.

The variable is read at the time get_logger is first called for a given service — not at import time.

Log file location and rotation

get_logger(service, log_dir) writes to {log_dir}/service.log.

• Default log_dir: ./logs relative to the working directory
• Rotation: 10 MB per file, 5 backups kept (service.log, service.log.1 … service.log.5)
• Encoding: UTF-8
• Also emits to stdout for NSSM AppStdout capture

The log_dir is created automatically (including parents) if it does not exist.

Idempotent logger creation

get_logger is safe to call multiple times with the same service name — subsequent calls return the cached logger without adding duplicate handlers:

logger_a = get_logger("my-service", log_dir="logs")
logger_b = get_logger("my-service", log_dir="logs")
assert logger_a is logger_b  # True

Zero dependencies

rfd-logging uses only the Python standard library: logging, json, datetime, pathlib, os. No third-party packages are installed.

Requirements

• Python ≥ 3.11