Python Logging Reviewer

Python Logging Reviewer

This skill audits a Python project's logging implementation against industry best practices, produces a prioritized improvement plan, and implements approved changes.

Before you start

Read the best-practices reference file to ground your audit:

cat references/best-practices.md

Use the practices and source citations in that file as your authoritative checklist. Do not invent rules — every finding you report should trace back to a named source in the reference file.

Workflow

Follow these four steps in order. Present the output of each step to the user and wait for approval before moving to the next.

Step 1 — Audit the codebase

Scan every Python file in the project. For each file, record:

1. Logger instantiation — How loggers are created. Flag any use of the root logger, hardcoded logger names, or basicConfig() called outside the entry point.
2. Log levels — Which levels are used and whether they match their semantic meaning. Flag DEBUG used for operational messages, WARNING used for expected behavior, etc.
3. Format and structure — Whether output is plain text or structured (JSON). Note the formatter class, fields included, and timestamp format.
4. Exception handling — Look for except blocks. Flag bare except: pass, exception handlers that log only the message string without exc_info=True, and duplicate exception logging across call layers.
5. Lazy formatting — Flag f-strings, .format(), or string concatenation inside log calls. These evaluate eagerly even when the log level is disabled.
6. Missing logging — Identify code paths with no logging: API/HTTP endpoints, database operations, retry loops, background tasks, signal handlers, and startup/shutdown.
7. Output destination — Flag hardcoded file paths in handlers. Note whether the project writes to stdout or manages its own log files.
8. Security — Flag any log call that could emit secrets, tokens, passwords, API keys, or PII. Look for logging of full request/response objects, auth headers, and database query parameters containing user data.
9. Library vs. application — If the project is a library (or contains library modules), check that those modules use NullHandler and do not call basicConfig().
10. Observability readiness — Note whether logs include correlation/request IDs, whether OpenTelemetry is present, and whether log attribute names follow OTel semantic conventions.

Produce a markdown table summarizing all findings. Group by file, and include the line number, the issue category (from the list above), a one-line description, and a severity tag: critical, recommended, or nice-to-have.

Severity guidelines:

• Critical — Security risks (PII/secrets in logs), swallowed exceptions, missing error-path logging, root logger misuse in production code.
• Recommended — Eager formatting, inconsistent log levels, plain-text format in production, missing correlation IDs, hardcoded file destinations.
• Nice-to-have — Timestamp format improvements, OTel semantic convention alignment, adding DEBUG-level tracing to internal utilities.

Step 2 — Recommendations with sources

For each finding from Step 1, recommend a concrete fix. Every recommendation must cite the specific best practice it's based on. Use the source abbreviations defined in references/best-practices.md:

• [PY-HOWTO] — Python logging HOWTO
• [PY-COOKBOOK] — Python Logging Cookbook
• [PY-STDLIB] — Python logging module docs
• [12FACTOR] — 12-Factor App, Factor XI (Logs)
• [OTEL] — OpenTelemetry Semantic Conventions
• [SRE-BOOK] — Google SRE Book, Ch. 6 (Monitoring Distributed Systems)
• [SRE-WORKBOOK] — Google SRE Workbook, Ch. 4 (Monitoring)
• [REAL-PYTHON] — Real Python logging best practices
• [HITCHHIKER] — The Hitchhiker's Guide to Python — Logging

Format each recommendation as:

### [severity] File: path/to/file.py, line N
**Finding:** <what's wrong>
**Fix:** <what to do>
**Source:** [SOURCE-TAG] — <one-sentence explanation of the cited practice>