--- name: python-logging-reviewer description: > Audit, plan, and fix logging in any Python project. Use this skill whenever someone asks to review, audit, improve, fix, or standardize logging in a Python codebase. Trigger on phrases like "check my logging", "improve observability", "standardize log output", "add structured logging", "review my logging setup", "fix my logs", "logging best practices", or any request that involves evaluating or improving how a Python project logs. Also trigger when someone mentions replacing print() with proper logging, adding correlation IDs, or making logs machine-readable. Even if the user just says "my logs are a mess" or "I can't debug production", this skill applies. --- # 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:** **Fix:** **Source:** [SOURCE-TAG] — ``` ### Step 3 — Implementation plan Group the recommendations into logical PR-sized batches. A good grouping: - **PR 1: Standardize logger initialization** — Switch all modules to `logging.getLogger(__name__)`, remove root logger usage, add `NullHandler` to library `__init__.py` files. - **PR 2: Fix exception logging** — Add `exc_info=True` or switch to `logger.exception()` in all except blocks, remove bare `except: pass`. - **PR 3: Add structured formatting** — Introduce a JSON formatter, configure it centrally, standardize timestamp to ISO 8601. - **PR 4: Secure log output** — Add scrubbing filters for sensitive fields, remove logging of full request/auth objects. - **PR 5: Fill logging gaps** — Add logging to unlogged code paths (API boundaries, retry loops, startup/shutdown). - **PR 6: Observability alignment** — Add correlation IDs, align attribute names with OTel semantic conventions, integrate trace context if OTel is present. Not every PR group will apply to every project. Skip groups that have no findings. Add groups if the project has issues not covered above. For each PR, list: 1. The files to change 2. A one-line summary of each change 3. The severity of the most critical finding in that PR 4. Estimated diff size (small / medium / large) Present the plan and wait for user approval before implementing. ### Step 4 — Implement After the user approves (they may approve all PRs or select specific ones), implement the changes one PR-group at a time. For each change: - Show a before/after diff - Explain in one sentence why the change matters - Ensure the change does not alter application logic — only logging After implementing each PR group, pause and let the user review before continuing. ## Constraints These rules are non-negotiable: - **Prefer stdlib `logging`** unless the project already uses `structlog`, `loguru`, or another library. Do not introduce a new logging library without asking. - **Never change application logic.** Only add, fix, or restructure logging code. - **Preserve existing log levels** unless the audit found a clear semantic mismatch. - **Never log secrets, tokens, passwords, or PII.** If existing code does this, flag it as critical and fix it. - **Do not remove existing log calls** unless they are duplicates or security risks. The goal is to improve coverage, not reduce it. ## Output format - The audit report (Step 1) is a markdown table. - The recommendations (Step 2) are structured markdown entries with source citations. - The implementation plan (Step 3) is a numbered list grouped by PR. - The implementation (Step 4) produces diffs with inline explanations.