pylogshield 0.4.1

📃 Documentation  ·  🔧 Report Bug

📋 Table of Contents

• Overview
• Features
• Quick Start
• Interactive TUI Viewer
• Terminal Demo
• Security Notes
• Contributing

📣 Overview

PyLogShield is a Python logging library for data professionals and developers who need reliable, secure logging with minimal setup. It extends Python's standard logging module with production-ready features: sensitive data masking, rate limiting, async logging, JSON formatting, context propagation, FastAPI middleware, and a rich CLI log viewer.

Your App  ──►  PyLogShield  ──►  Masking  ──►  Rate Limiter  ──►  Context  ──►  Handlers
                                                                              ├── Console / Rich
                                                                              ├── File / Rotating
                                                                              ├── JSON
                                                                              └── Async Queue

💡 Features

📌 Quick Start

Installation

pip install pylogshield

# FastAPI middleware support
pip install "pylogshield[fastapi]"

Basic Usage

from pylogshield import get_logger

logger = get_logger("my_app", log_level="INFO")

logger.info("Application started")
logger.warning("Low memory detected")
logger.error("Connection failed")

# Sensitive data is masked with mask=True
logger.info({"user": "john", "api_key": "sk-1234567890"}, mask=True)
# → {"user": "john", "api_key": "***"}

Production Setup

from pylogshield import get_logger, add_sensitive_fields
from pylogshield.context import log_context

add_sensitive_fields(["ssn", "credit_card"])

logger = get_logger(
    "production_app",
    log_level="INFO",
    enable_json=True,            # Structured JSON
    rotate_file=True,            # Auto-rotate log files
    rotate_max_bytes=10_000_000, # 10 MB per file
    rate_limit_seconds=0.5,      # Prevent log flooding
    use_queue=True,              # Non-blocking async logging
    queue_maxsize=50_000,        # Cap memory usage
    enable_metrics=True,         # Track log statistics
    enable_context=True,         # Structured context injection
)

with log_context(request_id="abc-123", user_id=42):
    logger.info("Processing payment", mask=True)
    # → {"message": "Processing payment", "request_id": "abc-123", "user_id": 42}

FastAPI Middleware

from fastapi import FastAPI
from pylogshield import get_logger
from pylogshield.middleware import PyLogShieldMiddleware

app = FastAPI()
logger = get_logger("api", enable_context=True, enable_json=True)
app.add_middleware(PyLogShieldMiddleware, logger=logger)

# Every log line automatically includes: request_id, http_method, http_path, client_ip

🖥️ Interactive TUI Viewer

Install the optional TUI extra and launch the full-screen interactive log viewer:

pip install "pylogshield[tui]"

pylogshield tui --file ~/.logs/myapp.log
pylogshield tui --file app.log --level ERROR        # start with ERROR+ filter
pylogshield tui --file app.log --follow             # start in live-follow mode

🖥️ Terminal Demo

Sensitive Data Masking — Before vs After

# Without mask=True
INFO  my_app  {"user": "john", "password": "hunter2", "token": "eyJhbGci..."}

# With mask=True  ✓
INFO  my_app  {"user": "john", "password": "***", "token": "***"}

JSON Output

{
  "timestamp": "2026-03-14T10:30:00.123+00:00",
  "host": "prod-server-01",
  "logger": "production_app",
  "level": "INFO",
  "message": "Processing payment",
  "request_id": "abc-123",
  "user_id": 42
}

CLI Log Viewer

╭──────────────────── Log Viewer ────────────────────╮
│ File:    /var/log/app/production.log               │
│ Limit:   200 lines                                 │
│ Level:   ERROR                                     │
│ Keyword: "timeout"                                 │
╰────────────────────────────────────────────────────╯

╭─────────────────────────────────────────────────────────────────╮
│ Timestamp                │ Level    │ Message                   │
├──────────────────────────┼──────────┼───────────────────────────┤
│ 2026-03-14T10:28:11.001  │ ERROR    │ DB timeout after 30s      │
│ 2026-03-14T10:29:54.332  │ ERROR    │ Connection timeout: redis  │
╰──────────────────────────┴──────────┴───────────────────────────╯
                          2 entries shown

# Follow live logs
pylogshield follow -f app.log -l ERROR -k "timeout"

# View last 50 lines
pylogshield view -f app.log -n 50 -l WARNING

# List log levels
pylogshield levels

⚠️ Security Notes

• mask=True masks sensitive values in strings, dicts, and exception .args. Traceback source lines are not redacted — they reflect the literal source text. Avoid storing sensitive values in local variables inside functions that may raise logged exceptions.
• ContextFilter skips context keys that conflict with standard LogRecord fields (e.g., msg, levelname) and emits a warnings.warn.
• PyLogShieldMiddleware sanitizes the incoming X-Request-ID header before injecting it into logs (truncated to 128 chars, non-alphanumeric characters stripped).

CI Pipeline

Every push to main and every pull request runs automatically via shared-workflows:

👪 Contributing

All contributions are welcome! Fork the repo, make your changes, and open a pull request. You can also open an issue with the label enhancement.

Don't forget to ⭐ star the project!

🔶 View all contributors

📃 Full Docs  ·  🔧 Report a Bug

(back to top)