feat/chore: commonizing logging into one spot (#180)

Author: wyattearp

README.md

@@ -255,6 +255,42 @@ If you want to use embedding models compatible with the OpenAI API (such as Alib
 
 This allows you to seamlessly switch to any OpenAI-compatible embedding service without code changes.
 
+### Logging
+
+DeepWiki uses Python's built-in `logging` module for diagnostic output. You can configure the verbosity and log file destination via environment variables:
+
+| Variable        | Description                                                        | Default                      |
+|-----------------|--------------------------------------------------------------------|------------------------------|
+| `LOG_LEVEL`     | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).             | INFO                         |
+| `LOG_FILE_PATH` | Path to the log file. If set, logs will be written to this file.   | `api/logs/application.log`   |
+
+To enable debug logging and direct logs to a custom file:
+```bash
+export LOG_LEVEL=DEBUG
+export LOG_FILE_PATH=./debug.log
+python -m api.main
+```
+Or with Docker Compose:
+```bash
+LOG_LEVEL=DEBUG LOG_FILE_PATH=./debug.log docker-compose up
+```
+
+When running with Docker Compose, the container's `api/logs` directory is bind-mounted to `./api/logs` on your host (see the `volumes` section in `docker-compose.yml`), ensuring log files persist across restarts.
+
+Alternatively, you can store these settings in your `.env` file:
+
+```bash
+LOG_LEVEL=DEBUG
+LOG_FILE_PATH=./debug.log
+```
+Then simply run:
+
+```bash
+docker-compose up
+```
+
+**Logging Path Security Considerations:** In production environments, ensure the `api/logs` directory and any custom log file path are secured with appropriate filesystem permissions and access controls. The application enforces that `LOG_FILE_PATH` resides within the project's `api/logs` directory to prevent path traversal or unauthorized writes.
+
 ## 🛠️ Advanced Setup
 
 ### Environment Variables

api/logging_config.py

@@ -0,0 +1,47 @@
+import logging
+import os
+from pathlib import Path
+
+
+def setup_logging(format: str = None):
+    """
+    Configure logging for the application.
+    Reads LOG_LEVEL and LOG_FILE_PATH from environment (defaults: INFO, logs/application.log).
+    Ensures log directory exists, and configures both file and console handlers.
+    """
+    # Determine log directory and default file path
+    base_dir = Path(__file__).parent
+    log_dir = base_dir / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    default_log_file = log_dir / "application.log"
+
+    # Get log level and file path from environment
+    log_level_str = os.environ.get("LOG_LEVEL", "INFO").upper()
+    log_level = getattr(logging, log_level_str, logging.INFO)
+    log_file_path = Path(os.environ.get(
+        "LOG_FILE_PATH", str(default_log_file)))
+
+    # ensure log_file_path is within the project's logs directory to prevent path traversal
+    log_dir_resolved = log_dir.resolve()
+    resolved_path = log_file_path.resolve()
+    if not str(resolved_path).startswith(str(log_dir_resolved) + os.sep):
+        raise ValueError(
+            f"LOG_FILE_PATH '{log_file_path}' is outside the trusted log directory '{log_dir_resolved}'"
+        )
+    # Ensure parent dirs exist for the log file
+    resolved_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Configure logging handlers and format
+    logging.basicConfig(
+        level=log_level,
+        format=format or "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[
+            logging.FileHandler(resolved_path),
+            logging.StreamHandler()
+        ],
+        force=True
+    )
+
+    # Initial debug message to confirm configuration
+    logger = logging.getLogger(__name__)
+    logger.debug(f"Log level set to {log_level_str}, log file: {resolved_path}")

api/main.py

@@ -7,25 +7,10 @@
 # Load environment variables from .env file
 load_dotenv()
 
-# --- Unified Logging Configuration ---
-# Determine the project's base directory (assuming main.py is in 'api' subdirectory)
-# Adjust if your structure is different, e.g., if main.py is at the root.
-# This assumes 'api/main.py', so logs will be in 'api/logs/application.log'
-LOG_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "logs")
-os.makedirs(LOG_DIR, exist_ok=True)
-LOG_FILE_PATH = os.path.join(LOG_DIR, "application.log")
-
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(lineno)d %(filename)s:%(funcName)s - %(levelname)s - %(message)s",
-    handlers=[
-        logging.FileHandler(LOG_FILE_PATH),
-        logging.StreamHandler()  # Also keep logging to console
-    ],
-    force=True  # Ensure this configuration takes precedence and clears any existing handlers
-)
-
-# Get a logger for this main module (optional, but good practice)
+from api.logging_config import setup_logging
+
+# Setup logging with detailed format for main
+setup_logging(format="%(asctime)s - %(lineno)d %(filename)s:%(funcName)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
 
 # Add the current directory to the path so we can import the api package

api/ollama_patch.py

@@ -6,11 +6,10 @@
 from adalflow.core.types import Document
 from adalflow.core.component import DataComponent
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
+# Unified logging setup
+from api.logging_config import setup_logging
+
+setup_logging()
 logger = logging.getLogger(__name__)
 
 class OllamaDocumentProcessor(DataComponent):

api/simple_chat.py

@@ -18,11 +18,10 @@
 from api.bedrock_client import BedrockClient
 from api.rag import RAG
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
+# Unified logging setup
+from api.logging_config import setup_logging
+
+setup_logging()
 logger = logging.getLogger(__name__)
 
 # Get API keys from environment variables

api/websocket_wiki.py

@@ -15,11 +15,10 @@
 from api.openrouter_client import OpenRouterClient
 from api.rag import RAG
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
+# Unified logging setup
+from api.logging_config import setup_logging
+
+setup_logging()
 logger = logging.getLogger(__name__)
 
 # Get API keys from environment variables

docker-compose.yml

@@ -15,8 +15,11 @@ services:
       - NODE_ENV=production
       - SERVER_BASE_URL=http://localhost:${PORT:-8001}
       - NEXT_PUBLIC_SERVER_BASE_URL=http://localhost:${PORT:-8001}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - LOG_FILE_PATH=${LOG_FILE_PATH:-api/logs/application.log}
     volumes:
-      - ~/.adalflow:/root/.adalflow  # Persist repository and embedding data
+      - ~/.adalflow:/root/.adalflow      # Persist repository and embedding data
+      - ./api/logs:/app/api/logs          # Persist log files across container restarts
     # Resource limits for docker-compose up (not Swarm mode)
     mem_limit: 6g
     mem_reservation: 2g