GAIA uses an advanced logging system built on Loguru with multiple outputs, automatic rotation, and structured logging.

​
Environment Variables

Configure logging behavior with these environment variables: 
LOG_LEVEL=INFO          # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_DIAGNOSE=false      # Enable detailed error diagnosis
LOG_BACKTRACE=true      # Include stack traces in logs
LOG_COLORIZE=true       # Enable colored console output

​
Log Files

The system automatically creates these log files in the logs/ directory:
FilePurposeRotationRetention
gaia-{date}.logGeneral application logsDaily30 days
errors-{date}.logErrors and critical issues10MB90 days
structured-{date}.jsonMachine-readable JSON logs50MB60 days
critical-{date}.logCritical issues only1MB1 year
performance-{date}.logPerformance logs (filtered)20MB7 days

​
Usage

​
Using Pre-configured Loggers

from app.config.loggers import auth_logger, mongo_logger

auth_logger.info("User authenticated successfully")
mongo_logger.error("Database connection failed")

​
Creating Contextual Loggers

from app.config.logging import get_contextual_logger

# Add context to all log messages
api_logger = get_contextual_logger("api", endpoint="/users", method="POST")
api_logger.info("Processing request")  # Includes context automatically

​
Function Logging Decorator

from app.decorators import log_function_call

@log_function_call
def process_data(data: dict):
    return processed_data  # Automatically logs execution time

​
Custom Log Levels

Three custom levels are available with special formatting:
  • PERFORMANCE ⚡ - Performance metrics and timing
  • AUDIT 📊 - Audit trail events
  • SECURITY 🔒 - Security-related events
from loguru import logger

logger.log("PERFORMANCE", "Query executed in 0.05s")
logger.log("AUDIT", "User permissions changed")
logger.log("SECURITY", "Failed login attempt detected")

​
Production Tips

  • Set LOG_LEVEL=INFO or WARNING in production to reduce verbosity
  • Use LOG_DIAGNOSE=false in production for security
  • Monitor log file sizes and rotation policies
  • Parse structured JSON logs for monitoring and analysis