Skip to content

v0.4.10 - Structured Logging Across All Layers (2025-12-25)

What Changed?

This release adds comprehensive structured logging throughout the kazunoko library for better visibility into operations and troubleshooting. All seven core modules now integrate loguru for consistent, contextual logging of device communication, measurement workflows, and response parsing. Users benefit from both human-readable console output and machine-readable JSON logs for developer analysis.

What's New

Main Feature: Structured Logging System

What it does: All core modules (device, measure, parser, command, formatter, mock, log) now emit contextual logging at appropriate levels:

  • DEBUG: Implementation details, port detection, serial communication timing
  • INFO: Progress milestones, successful command execution, event collection counts
  • SUCCESS: Significant completions (device connection, measurement setup, setup completion)
  • WARNING: Recoverable issues (response timeouts, failed RTC sync)
  • ERROR: Failures with full stack traces (connection errors, parsing failures)

How to use it:

  1. By default, only ERROR messages appear on console (minimal output)
  2. Enable DEBUG output with --verbose flag: kazunoko --verbose read 100
  3. JSON logs are always saved to platform-specific directory for analysis
  4. View structured logs: tail -f ~/Library/Logs/kazunoko/kazunoko.json | jq .

Code example:

from kazunoko import connect, Command
from kazunoko.log import setup_logger

# Setup logging (automatically called by CLI)
setup_logger(verbose=True)  # Enable DEBUG output

# All operations now include logging
with connect() as device:
    cmd = Command(device)
    resp = cmd.status()  # Logs: device connection, command transmission, response reception
    # Logs show elapsed time, port, and command details

Installation

Quick Start

# Get the release
git checkout v0.4.10

# Setup
task env:setup

# Run CLI with verbose logging enabled
uv run kazunoko --verbose --help

What's Different from the Last Version?

✅ Added

  • Structured logging system across all core modules (device, measure, parser, command, formatter, mock, log)
  • log.py module with setup_logger() function for dual-output logging (console + JSON file)
  • Comprehensive logging to device layer: serial communication, command transmission, response reception
  • Logging to measurement layer: event reading, setup steps, metadata collection
  • Logging to parser layer: JSON parsing, response validation, threshold parsing
  • Logging to command layer: multi-step operations like thresholds()
  • Logging to formatter layer: format selection and output generation
  • Logging to mock device layer: event loading, response generation
  • Documentation in README.md on logging usage and tee/redirection examples
  • XDG-compliant log directory with daily rotation and 7-day retention

🔧 Changed

  • Console logging default: ERROR level only (no INFO/DEBUG clutter)
  • Added --verbose/-v flag to enable DEBUG console output for troubleshooting
  • All logging uses loguru for structured, contextual information
  • File logging: Always DEBUG level, JSON format for machine analysis
  • All modules now emit consistent log levels: DEBUG, INFO, SUCCESS, WARNING, ERROR

🐛 Fixed

  • Removed f-string prefixes and trailing whitespace from linting

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No breaking changes to public API
  • Existing code continues to work unchanged
  • Logging is purely additive; no behavioral changes to library functions
  • Console output is less verbose by default (improvements for scripts)
  • New --verbose flag is optional

Tests Passed

  • ✅ Builds without errors
  • ✅ All modules lint correctly with ruff
  • ✅ Type checking passes with mypy
  • ✅ CLI commands execute with logging enabled
  • ✅ Mock device provides consistent test data
  • ✅ JSON logs serialize correctly with structured metadata

Release Details

  • Date: 2025-12-25
  • Version: v0.4.10
  • Files Changed: 14 (device.py, measure.py, parser.py, command.py, formatter.py, mock.py, log.py, cli.py, README.md, CLAUDE.md, init.py, pyproject.toml, CHANGELOG.md, uv.lock)
  • Commits: 11 feature commits, 1 refactor commit, 1 documentation commit

Major commits:

  • f24a3b4 - Device layer logging with serial communication details
  • bb0514b - Measurement layer logging with event tracking
  • ea6cf90 - Parser layer logging with JSON validation
  • fa78e99 - Mock device layer logging with event loading
  • 2e8c2a3 - Formatter layer logging with format conversion
  • 05fff92 - Command layer logging with multi-step operations
  • 7fc457b - Logger setup module with dual-output configuration
  • 04aa95a - README documentation with logging section
  • e13e0ca - README examples with tee and shell redirection

Next Steps

  • Future Work: Consider async event streaming for high-frequency data collection
  • Roadmap: Enhanced log filtering and export utilities
  • Community: Share JSON logs from the field to improve detector protocol understanding