Skip to content

logging

Centralized Loguru Configuration for Tux Discord Bot.

This module provides clean, standardized logging setup following loguru best practices: - Single global logger configuration - Environment-based configuration - Structured logging helpers - Third-party library log interception - IDE-clickable file paths

Configuration Priority

Log level is determined in this order (highest to lowest): 1. Explicit level parameter (for testing) 2. CONFIG.LOG_LEVEL from .env file 3. CONFIG.DEBUG=1 sets DEBUG level 4. Default "INFO"

Usage

Call once at application startup:

Text Only
from tux.shared.config import CONFIG
from tux.core.logging import configure_logging

configure_logging(config=CONFIG)

For debugging specific issues, override the level:

Text Only
configure_logging(level="DEBUG")

Classes:

  • StructuredLogger –

    Helper class for structured logging with consistent context.

Functions:

Classes

_LoggingState

Prevents duplicate logging configuration.

StructuredLogger

Helper class for structured logging with consistent context.

Methods:

  • performance –

    Log performance metrics with structured context.

  • database –

    Log database operations with structured context.

  • api_call –

    Log external API calls with structured context.

Functions

performance staticmethod
Python
performance(operation: str, duration: float, **context: Any) -> None

Log performance metrics with structured context.

Parameters:

  • operation (str) –

    Name of the operation being measured.

  • duration (float) –

    Duration of the operation in seconds.

  • **context (Any, default: {} ) –

    Additional context to bind to the log entry.

Examples:

Python Console Session
>>> StructuredLogger.performance("database_query", 0.123, query="SELECT * FROM users")
database staticmethod
Python
database(query: str, duration: float | None = None, **context: Any) -> None

Log database operations with structured context.

Parameters:

  • query (str) –

    The SQL query being executed.

  • duration (float | None, default: None ) –

    Query execution duration in seconds.

  • **context (Any, default: {} ) –

    Additional context like table names, row counts, etc.

Examples:

Python Console Session
>>> StructuredLogger.database("INSERT INTO users", duration=0.045, rows_affected=1)
api_call staticmethod
Python
api_call(
    method: str,
    url: str,
    status: int | None = None,
    duration: float | None = None,
    **context: Any,
) -> None

Log external API calls with structured context.

Parameters:

  • method (str) –

    HTTP method (GET, POST, etc.).

  • url (str) –

    The API endpoint URL.

  • status (int | None, default: None ) –

    HTTP response status code.

  • duration (float | None, default: None ) –

    Request duration in seconds.

  • **context (Any, default: {} ) –

    Additional context like response size, error details, etc.

Examples:

Python Console Session
>>> StructuredLogger.api_call("GET", "https://api.github.com/user", status=200, duration=0.234)

Functions

configure_testing_logging

Python
configure_testing_logging() -> None

Configure logging specifically for testing environment.

This sets up logging with DEBUG level and testing-appropriate configuration. Call this once at test startup.

configure_logging

Python
configure_logging(
    environment: str | None = None,
    level: str | None = None,
    config: Config | None = None,
) -> None

Configure the global loguru logger for the Tux application.

This is the main entry point for logging configuration. Call once at startup.

Parameters:

  • environment (str | None, default: None ) –

    Deprecated parameter, kept for backward compatibility.

  • level (str | None, default: None ) –

    Explicit log level override (for testing). Highest priority.

  • config (Config | None, default: None ) –

    Config instance with LOG_LEVEL and DEBUG from .env file.

Examples:

Normal usage (respects .env configuration): >>> from tux.shared.config import CONFIG >>> configure_logging(config=CONFIG)

Override for testing: >>> configure_logging(level="DEBUG")

_configure_level_colors

Python
_configure_level_colors() -> None

Configure custom colors for each log level.

_determine_log_level

Python
_determine_log_level(level: str | None, config: Config | None) -> str

Determine the log level from multiple sources.

Priority (highest to lowest): 1. Explicit level parameter 2. config.LOG_LEVEL (from .env) 3. config.DEBUG (sets DEBUG) 4. Default "INFO"

Parameters:

  • level (str | None) –

    Explicit level override.

  • config (Config | None) –

    Config instance from .env.

Returns:

  • str –

    The determined log level.

_add_console_handler

Python
_add_console_handler(log_level: str) -> None

Add console handler with custom formatting.

Uses a dynamic stderr sink for robustness against stream wrapping (e.g., by pytest, IDEs, cloud platforms).

Parameters:

  • log_level (str) –

    The minimum log level to display.

_format_record

Python
_format_record(record: Any) -> str

Format log record with IDE-clickable file paths and proper escaping.

For tux.* modules: Shows clickable path (src/tux/core/app.py:167) For third-party: Shows module:function (urllib3.connectionpool:_make_request:544)

Parameters:

  • record (Any) –

    The loguru Record object.

Returns:

  • str –

    Formatted log message with escaped special characters.

_get_relative_file_path

Python
_get_relative_file_path(record: Any) -> str

Get file path relative to project root (from src/ directory).

Parameters:

  • record (Any) –

    The loguru Record object.

Returns:

  • str –

    Relative file path from src/ (e.g., "src/tux/core/app.py").

_escape_format_chars

Python
_escape_format_chars(text: str | Any) -> str

Escape special characters that could be interpreted as format placeholders.

Escapes: - Curly braces {{ }} to prevent format string errors - Angle brackets <> to prevent color tag errors

Parameters:

  • text (str | Any) –

    Text to escape.

Returns:

  • str –

    Escaped text safe for loguru formatting.

_configure_third_party_logging

Python
_configure_third_party_logging() -> None

Configure logging interception for third-party libraries.

This sets up an InterceptHandler that routes standard library logging calls to loguru, maintaining proper source attribution for all logs.

Process: 1. Create InterceptHandler to bridge logging -> loguru 2. Replace root logging handler globally 3. Configure specific library loggers with InterceptHandler 4. Set appropriate minimum levels for third-party libraries

verify_logging_interception

Python
verify_logging_interception() -> None

Verify third-party library logging configuration (debug utility).

Logs the configuration of all known third-party loggers, showing which handlers are attached and their current levels.

This is automatically called when DEBUG level is active.