Skip to content

v0.4.1 - CLI Logging Enhancement (2025-12-24)

What Changed?

This patch release integrates structured logging across all CLI commands. Every command now records execution details, parameters, and results to JSON log files for developer debugging and analysis. User-facing feedback remains consistent with colored console output while operational context is captured for post-hoc investigation.

What's New

Enhancement: CLI Command Logging Integration

What it does: All CLI commands (query, read, measure, status) now automatically log their execution with setup_logger(). Each command captures operational context including device port, command parameters, and results in structured JSON format. Errors include full stack traces for debugging.

How to use it:

# Run any command - logging happens automatically
kazunoko status
kazunoko read 10
kazunoko measure --duration 30 --poll-count 5

# Enable verbose logging to console
kazunoko -v status
kazunoko -v read 10

# Check log files
cat ~/.cache/kazunoko/osechi/kazunoko.json

Log file example (pretty-printed):

{
  "text": "2025-12-24 14:32:15 | INFO     | Executing command",
  "record": {
    "elapsed": {"seconds": 0.123},
    "exception": null,
    "extra": {
      "command": "STATUS",
      "device": "/dev/ttyUSB0"
    },
    "level": {"icon": "ℹī¸", "name": "INFO", "no": 20},
    "message": "Executing command",
    "time": "2025-12-24T14:32:15.123456+00:00"
  }
}

What gets logged:

  • query command: Command execution, device port, command string, success/failure
  • read command: Device time sync, event collection start (mode & count), completion with total events
  • measure command: Session setup, threshold settings, RTC sync, completion with event count
  • status command: Status command execution and device port
  • All commands: Full exception stack traces on errors via exc_info=True

Installation

Quick Start

# Get the release
git checkout v0.4.1

# Setup
uv sync

# Use in your code
kazunoko -v status  # With verbose console logging

What's Different from the Last Version?

✅ Added

  • Logging integration for all CLI commands (query, read, measure, status)
  • Extra context fields in JSON logs: device port, command parameters, event counts, modes
  • Full stack traces in error logs via exc_info=True for better debugging
  • Verbose mode displays DEBUG level messages to console for troubleshooting

🔧 Changed

  • None - this is a pure addition; no breaking changes to existing APIs or CLI interfaces

🐛 Fixed

  • None

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All CLI commands work exactly as before from user perspective
  • Logging is transparent - no changes to command arguments, output format, or behavior
  • Log files are written to XDG cache directory; no interference with user data
  • Existing scripts and workflows continue to work unchanged

Tests Passed

  • ✅ Builds without errors
  • ✅ Pre-commit hooks pass
  • ✅ All CLI commands execute successfully
  • ✅ JSON log files generated correctly with proper serialization
  • ✅ Verbose flag enables DEBUG logging without errors

Release Details

  • Date: 2025-12-24
  • Version: v0.4.1
  • Files Changed: 1 (cli.py with logging integration)
  • Commits:
  • 6cb83f5 refactor: integrate logging module into CLI with global verbose flag
  • d94c398 refactor: add logger to error_handler decorator
  • 68871bd refactor: add logger to query command
  • 51653a2 refactor: add logger to read command
  • 0dafb2c refactor: add logger to measure command
  • 711ac57 refactor: add logger to status command
  • 8cb9ac7 bump: version 0.4.0 → 0.4.1

Next Steps

  • Integrate log file analysis utilities for parsing and filtering JSON logs
  • Add log viewer command for interactive log exploration
  • Consider log level configuration per module
  • User feedback on logging verbosity and additional context fields needed