Logging

This document details the structured logging standards and sensitive data policies.

For correlation IDs, metrics, and tracing standards, see: Observability (docs/backend/03_development/observability.md). For PII and secrets handling rules, see: Data Handling & Secrets (docs/backend/01_security/data_handling.md).

Structured Logging

Standard Location: logger.py

Usage:

from logger import logger

# Info level - normal operations
logger.info("Processing request for user: %s", user_id)

# Warning level - potential issues
logger.warning("Rate limit approaching for user: %s", user_id)

# Error level - errors occurred
logger.error("Failed to fetch data: %s", error)

# Exception level - with full traceback
try:
    result = await operation()
except Exception as e:
    logger.exception("Operation failed")  # Includes traceback
    raise

Configuration

• Uses logtail-python for aggregation (optional)
• Uses rich for formatted terminal output
• Configurable via env vars (e.g., LOGGER_SOURCE_TOKEN)

Sensitive Data Policy

NEVER log:

• Full JWT tokens (log last 4 chars only)
• Passwords (hashed or plain)
• API keys (full)
• PII (Personally Identifiable Information) unless necessary and secured
• Payment card information

Sanitization: Ensure any logged objects (like request bodies) are sanitized of sensitive fields before logging.