Runbook: Logging Failing

Trigger

• No new entries in logs/app.log.
• App crashes on startup with logging-related error.
• Wrong log path or no write permission.

Fast triage

1. Check .env: LOG_DIR, LOG_FILE_NAME, LOG_LEVEL.
2. Check directory and file permissions for logs/.
3. Start app and send test request: make run, then call /health.

Most common causes

• Invalid/unexpected LOG_LEVEL value.
• Non-writable log directory.
• App started from a different folder; relative paths break.
• Logging code changed but startup in app/main.py does not match.

Recovery steps

1. Reset to known-good defaults in .env: LOG_DIR=logs, LOG_FILE_NAME=app.log, LOG_LEVEL=INFO.
2. Restart app: stop server and run make run again.
3. Verify request log line appears after calling /health.
4. If still failing, inspect app/core/logging.py path/handler setup.

Exit criteria

• New requests write lines to logs/app.log.
• App startup is stable.
• make test still passes.

Follow-up

• If this changes observability policy, add or update an ADR.
• If it is a new failure pattern, update this runbook.

Page history