How to Configure DeepWiki Logging: Setting LOG_LEVEL and LOG_FILE_PATH

Configure DeepWiki logging by setting the LOG_LEVEL and LOG_FILE_PATH environment variables before starting the application, which controls minimum severity and output destination via the setup_logging() function in api/logging_config.py.

DeepWiki, an open-source project by AsyncFuncAI, centralizes its logging configuration through environment variables to ensure flexible deployment across development and production environments. Understanding how to configure DeepWiki logging allows you to control verbosity, file rotation, and output destinations without modifying source code.

Understanding DeepWiki's Logging Architecture

Core Logging Module

All logging functionality resides in api/logging_config.py. The setup_logging() function executes automatically when any public API module (such as api/main.py, api/simple_chat.py, or api/websocket_wiki.py) imports it. This ensures the logging infrastructure is ready before any business logic executes.

The function performs three critical operations:

1. Creates a trusted log directory at api/logs/ relative to the source file
2. Validates environment variables for security and correctness
3. Configures dual handlers: a RotatingFileHandler for persistent storage and a console handler for real-time monitoring

Environment Variable Overview

DeepWiki recognizes four environment variables for logging configuration:

Variable	Purpose	Default Value
LOG_LEVEL	Minimum severity to emit (DEBUG, INFO, WARNING, ERROR, CRITICAL)	INFO
LOG_FILE_PATH	Absolute or relative path for log output (must resolve inside logs/ directory)	api/logs/application.log
LOG_MAX_SIZE	Maximum file size in MiB before rotation triggers	10
LOG_BACKUP_COUNT	Number of archived log files to retain	5

Configuring LOG_LEVEL for DeepWiki

The LOG_LEVEL environment variable accepts standard Python logging level names. The implementation normalizes input using .upper(), making the configuration case-insensitive. If you provide an invalid level name, the system gracefully falls back to INFO.

Set the level based on your operational needs:

• DEBUG: Verbose output including function entry points and variable states (development only)
• INFO: Standard operational messages (recommended for production)
• WARNING: Only unexpected conditions that don't prevent operation
• ERROR: Runtime failures that prevent specific operations
• CRITICAL: System-wide failures requiring immediate attention

export LOG_LEVEL=DEBUG
python -m api.main

Setting LOG_FILE_PATH and Rotation Settings

Path Security and Validation

DeepWiki implements path-traversal protection by validating that LOG_FILE_PATH resolves within the trusted api/logs/ directory. You may specify subdirectories (e.g., logs/production/app.log), but attempts to escape the logs folder (e.g., ../../../etc/passwd) will be blocked by the security check in api/logging_config.py.

Log Rotation Configuration

The system uses Python's logging.handlers.RotatingFileHandler to manage disk space automatically. When the current log file exceeds LOG_MAX_SIZE MiB, the handler:

1. Renames the current file by appending .1
2. Shifts existing backups (.1 becomes .2, etc.)
3. Creates a fresh log file
4. Deletes the oldest backup if exceeding LOG_BACKUP_COUNT

export LOG_FILE_PATH=logs/production/api.log
export LOG_MAX_SIZE=50
export LOG_BACKUP_COUNT=10
python -m api.main

Practical Configuration Examples

Shell Environment Configuration

For immediate testing or containerized deployments, export variables before launching the application:

export LOG_LEVEL=DEBUG
export LOG_FILE_PATH=logs/debug_session.log
export LOG_MAX_SIZE=20
export LOG_BACKUP_COUNT=3

python -m api.main

Using a .env File

For persistent configuration across restarts, create a .env file in the project root:

LOG_LEVEL=WARNING
LOG_FILE_PATH=logs/errors_only.log
LOG_MAX_SIZE=5
LOG_BACKUP_COUNT=3

When the application starts via docker-compose or a process manager that loads environment files, DeepWiki will automatically apply these settings to the setup_logging() function.

Customizing Log Format Programmatically

For specialized debugging sessions, override the default format before importing other application modules:

from api.logging_config import setup_logging

custom_format = "%(asctime)s | %(levelname)s | %(module)s:%(lineno)d | %(message)s"
setup_logging(format=custom_format)

# Import application modules after logging is configured

import api.main

Summary

• DeepWiki logging is controlled through environment variables read by api/logging_config.py at application startup.
• Set LOG_LEVEL to control verbosity using standard Python levels (DEBUG, INFO, WARNING, ERROR, CRITICAL).
• Configure LOG_FILE_PATH to customize output location, with automatic validation preventing directory traversal outside api/logs/.
• Rotation settings (LOG_MAX_SIZE and LOG_BACKUP_COUNT) manage disk usage automatically using RotatingFileHandler.
• Apply changes by setting environment variables before launching the process via shell exports, .env files, or container configuration.

Frequently Asked Questions

How do I enable debug logging in DeepWiki?

Set the LOG_LEVEL environment variable to DEBUG before starting the application. This will emit verbose messages including function entry points and internal state information. For example: export LOG_LEVEL=DEBUG && python -m api.main. The change takes effect immediately on the next startup because setup_logging() in api/logging_config.py reads this variable at import time.

Can I write logs to a location outside the api/logs directory?

No. DeepWiki implements a security check in api/logging_config.py that validates LOG_FILE_PATH resolves within the trusted api/logs/ directory. This prevents path traversal attacks. You may create subdirectories within api/logs/ (e.g., logs/production/app.log), but attempting to use paths like ../../../var/log/app.log will be blocked by the validation logic.

What happens when the log file reaches the maximum size?

When the log file exceeds the size specified by LOG_MAX_SIZE (default 10 MiB), DeepWiki's RotatingFileHandler automatically rotates the file. The current file is renamed with a .1 extension, existing backups are shifted (.1 becomes .2, etc.), and a fresh log file is created. If the number of backups exceeds LOG_BACKUP_COUNT (default 5), the oldest archive is deleted to manage disk space automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}