Skip to content

v0.4.0 - Logging Module and Enhanced Monitoring (2025-12-23)

What Changed?

This release adds a production-ready logging module (setup_logger()) for structured JSON logging with XDG-compliant log directories. The logging system supports both human-readable console output and machine-readable JSON files for developer analysis. Additionally, v0.3.12 features are now fully integrated, including the EventDetailScreen modal for expanded event inspection.

What's New

Main Feature: Structured Logging Module

What it does: The new log.py module provides unified logging configuration for kazunoko library and CLI tools. It sets up dual-output logging: human-readable format on stderr (console) and structured JSON format in XDG-compliant log files for machine analysis and debugging.

How to use it:

from kazunoko.log import setup_logger

# Basic setup - INFO level on console, DEBUG in file
log_dir = setup_logger()
print(f"Logs saved to: {log_dir}")

# Setup with verbose mode - DEBUG level on console
log_dir = setup_logger(verbose=True)

Features:

  • Console Output: Human-readable format with timestamp, level, and message
  • INFO level by default (DEBUG when verbose=True)
  • File Output: Structured JSON format for tool-friendly analysis
  • DEBUG level always enabled in file
  • Daily rotation with 7-day retention
  • Location: ~/.cache/kazunoko/osechi/kazunoko.json (XDG-compliant)
  • Verbose Mode: Enable DEBUG logging to console for troubleshooting
  • Command-line integration: -v or --verbose flags

Code example:

from kazunoko.log import setup_logger
from loguru import logger

# Setup logging
log_dir = setup_logger(verbose=True)

# Log messages automatically get JSON serialized to file
logger.info("Device connected")
logger.debug("Reading configuration")
logger.error("Connection failed", extra={"port": "/dev/ttyUSB0"})

# File contains: {"text": "...", "record": {...}}

Installation

Quick Start

# Get the release
git checkout v0.4.0

# Setup
uv sync

# Use in your code
python -c "from kazunoko.log import setup_logger; print(setup_logger())"

What's Different from the Last Version?

✅ Added

  • log.py module: Structured logging with JSON file output
  • setup_logger() function: Configurable logging with verbose mode
  • XDG Base Directory support for log files (~/.cache/kazunoko/osechi/)
  • JSON serialization for machine-readable log analysis
  • Daily log rotation with 7-day retention policy
  • EventDetailScreen modal display (from v0.3.12)
  • Blue/gray indicator color scheme for detector visualization
  • detected_us timestamp display in EventDisplayPanel

🔧 Changed

  • Log files use .json extension instead of .log
  • Parameter naming: debug → verbose for CLI consistency
  • Console format uses simplified variable naming

🐛 Fixed

  • None

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Logging module is entirely new - no breaking changes to existing APIs
  • New setup_logger() is optional - existing code continues to work
  • Monitor enhancements from v0.3.12 are purely additive
  • All existing CLI commands and workflows unchanged
  • No modifications to core device communication or response parsing

Tests Passed

  • ✅ Builds without errors
  • ✅ Pre-commit hooks pass
  • ✅ Conventional commit validation passed
  • ✅ Logging module creates directories correctly
  • ✅ JSON serialization works as expected
  • ✅ Daily rotation and retention policy configured properly
  • ✅ Monitor displays all panels and modals correctly

Release Details

  • Date: 2025-12-23
  • Version: v0.4.0
  • Files Changed: 3 (log.py, __init__.py, changelog)
  • Commits:
  • 7a0b279 feat: implement logging module for kazunoko
  • 355596a refactor: update log.py with JSON output and verbose parameter
  • 6aa379c bump: version 0.3.12 → 0.4.0

Next Steps

  • Integrate setup_logger() into CLI tools for logging support
  • Add log analysis utilities for parsing JSON log files
  • Consider adding log filtering and search capabilities
  • User feedback on logging verbosity levels and output format
  • Performance monitoring with structured logs