Skip to content

Logging Module

The logging module provides unified logging configuration for kazunoko library and CLI tools.

Logging configuration for kazunoko

Provides unified logging setup for the kazunoko library and CLI tools. Uses loguru for structured logging with both console and file output.

setup_logger(log_level='error')

Configure loguru logger with console and file output.

Sets up logging to both stderr (for console output) and a daily-rotated JSON log file in the user's cache directory following XDG Base Directory spec.

Console behavior:

  • "debug": DEBUG level (implementation details, timing)
  • "info": INFO level (progress milestones)
  • "success": SUCCESS level (significant completions)
  • "warning": WARNING level (recoverable issues)
  • "error": ERROR level only (failures, default)

File logging:

  • Always DEBUG level for complete record
  • Structured JSON format for machine-readable analysis by developers
  • Daily rotation with 7-day retention

Parameters:

Name Type Description Default
log_level LogLevel

Console log level - "debug" (detailed), "info" (progress), "success" (completions), "warning" (issues), or "error" (failures only, default). File logging is always DEBUG. Defaults to "error".

 'error'

Returns:

Type Description
Path

Path to the log file directory
Example 
from kazunoko.log import setup_logger

# Default setup: ERROR level only (production)
log_dir = setup_logger()

# Info mode: progress messages (interactive)
log_dir = setup_logger(log_level="info")

# Debug mode: detailed logging (development)
log_dir = setup_logger(log_level="debug")
Note

Console output uses human-readable format while file output uses JSON format for structured analysis and debugging. For development troubleshooting, provide the JSON log file from the log directory to developers.

Source code in src/kazunoko/log.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def setup_logger(log_level: LogLevel = "error") -> Path:
    """
    Configure loguru logger with console and file output.

    Sets up logging to both stderr (for console output) and a daily-rotated
    JSON log file in the user's cache directory following XDG Base Directory spec.

    **Console behavior:**

    - "debug": DEBUG level (implementation details, timing)
    - "info": INFO level (progress milestones)
    - "success": SUCCESS level (significant completions)
    - "warning": WARNING level (recoverable issues)
    - "error": ERROR level only (failures, default)

    **File logging:**

    - Always DEBUG level for complete record
    - Structured JSON format for machine-readable analysis by developers
    - Daily rotation with 7-day retention

    Args:
        log_level: Console log level - "debug" (detailed), "info" (progress),
            "success" (completions), "warning" (issues), or "error" (failures only, default).
            File logging is always DEBUG. Defaults to "error".

    Returns:
        Path to the log file directory

    Example:
        ```python
        from kazunoko.log import setup_logger

        # Default setup: ERROR level only (production)
        log_dir = setup_logger()

        # Info mode: progress messages (interactive)
        log_dir = setup_logger(log_level="info")

        # Debug mode: detailed logging (development)
        log_dir = setup_logger(log_level="debug")
        ```

    Note:
        Console output uses human-readable format while file output uses JSON format
        for structured analysis and debugging. For development troubleshooting, provide
        the JSON log file from the log directory to developers.
    """
    # Remove default handler
    logger.remove()

    # Get XDG-compliant log directory
    log_dir = Path(platformdirs.user_log_dir("kazunoko", "osechi"))
    log_dir.mkdir(parents=True, exist_ok=True)

    # Console format (human-readable)
    fmt = "{time:YYYY-MM-DD HH:mm:ss} | <level>{level: <8}</level> | {name}:L{line} | {function} | {message}"

    # Console output (stderr) - mapped from log_level parameter
    logger.add(sys.stderr, format=fmt, level=log_level.upper())

    # File output with JSON format for structured analysis
    logger.add(
        log_dir / "kazunoko.json",
        format="{message}",
        level="DEBUG",
        rotation="00:00",
        retention="7 days",
        serialize=True,  # Enable JSON serialization
    )

    return log_dir