social-app/.trellis/spec/backend/logging-guidelines.md

Logging Guidelines

How logging is done in this project.

---

Overview

Backend uses structlog integrated with stdlib logging configuration.

Evidence:

• Logger factory: backend/src/core/logging/logger.py
• Logging config and processors: backend/src/core/logging/config.py
• Formatter/JSON pipeline: backend/src/core/logging/formatters.py
• Request context middleware: backend/src/core/logging/middleware.py
• Runtime usage examples: backend/src/app.py, backend/src/v1/todo/service.py

---

Log Levels

Observed level usage:

• debug: low-level diagnostic events (e.g., JWT success branch)
  • backend/src/v1/users/dependencies.py
• info: normal lifecycle and business events
  • backend/src/app.py (startup/initialized)
  • backend/src/v1/todo/service.py (todo_created, todo_updated, etc.)
• warning: recoverable issues, unauthorized attempts, validation problems
  • backend/src/app.py (HTTP and validation warnings)
  • backend/src/v1/todo/service.py (unauthorized operations)
• error / exception: failures needing investigation
  • backend/src/app.py (logger.exception("Unhandled error"))
  • repositories with logger.exception(...) before re-raise

---

Structured Logging

Conventions from current setup:

1. Always obtain logger through core.logging.get_logger(...).
2. Use structured fields (keyword args / bound context), not string interpolation only.
3. Request-level context can be attached by RequestContextMiddleware (request_id, method, path, client_ip, user_id) when the middleware is mounted.
4. JSON output is enabled by default (runtime.log_json = True), with fallback plain formatter supported.

Examples:

• backend/src/core/logging/middleware.py binds and propagates request context (middleware implementation)
• backend/src/core/logging/config.py configures processors and handlers
• backend/tests/integration/test_fastapi_logging_integration.py mounts the middleware in test FastAPI app and asserts context fields in emitted logs

Current wiring note:

• backend/src/app.py currently does not call app.add_middleware(RequestContextMiddleware); treat middleware context fields as opt-in wiring, not guaranteed global behavior.

---

What to Log

Log these consistently:

• Service lifecycle events (startup/shutdown/init failures)
  • backend/src/app.py
  • backend/src/services/base/service_interface.py
• Security/auth failures and unauthorized access attempts
  • backend/src/v1/users/dependencies.py
  • backend/src/v1/todo/service.py
• Database or external dependency failures with stable context fields
  • backend/src/v1/*/repository.py patterns
  • backend/src/services/base/{redis.py,supabase.py}

---

What NOT to Log

Sensitive data should be redacted; avoid raw secrets/tokens/credentials.

Evidence:

• Sensitive field defaults in backend/src/core/config/settings.py (password, token, authorization, etc.)
• Redaction processor tests:
  • backend/tests/unit/test_logging_filters.py
  • backend/tests/unit/test_logging_config.py

Avoid logging:

• Raw access tokens / refresh tokens / cookies
• Passwords, API keys, secret values
• Full untrusted payload dumps containing PII

---

Anti-patterns / Forbidden Patterns

• Do not use print() in backend runtime code; use project logger APIs.
  • Rule source: backend/AGENTS.md
• Do not bypass logging config by ad-hoc logger setup in feature modules.
  • Use configure_logging(...) from backend/src/core/logging/config.py.
• Do not log sensitive fields without redaction.
• Do not assume request context fields exist unless RequestContextMiddleware is explicitly mounted.

---

Uncertainties (documented, not invented)

• This repo has tests for logging behavior and redaction, but no single documented required schema for every log event across all modules (beyond context fields and processor output).
• core.logging.middleware.register_exception_handlers(...) exists but app-level error handling is primarily in backend/src/app.py; effective production wiring should remain explicit per app bootstrap.