Skip to content

v0.4.6 - Real-time Monitor Logging Integration (2025-12-24)

What Changed?

This release integrates structured logging into the monitor.py real-time TUI application. The monitor script now uses kazunoko's centralized logging system (kazunoko.log.setup_logger()) for consistent JSON-formatted logging across all example scripts. All monitoring operations and event processing are now logged to JSON files for debugging and post-hoc analysis while maintaining full backward compatibility.

What's New

Main Feature: Centralized Logging in Real-time Monitor

What it does: The monitor.py script now integrates with kazunoko's unified logging system, providing structured JSON logging for all monitoring operations including event reception, TUI updates, and error handling. This ensures consistency across all example scripts (get_events.py, get_runs.py, get_thresholds.py, and monitor.py).

How to use it: Simply run the monitor script as before - all enhancements are automatic and transparent:

# Monitor piped input from detector
uv run kazunoko generate ... | uv run monitor.py

# Monitor a directory for new event files
uv run monitor.py --watch /path/to/data/directory

# Monitor with detailed logging
uv run monitor.py 2> monitor.log

Logs are automatically saved to the platform-specific directory (e.g., ~/Library/Logs/kazunoko/kazunoko.json on macOS) with detailed records of all monitoring operations for debugging and performance analysis.

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Setup
task env:setup

# Run monitor
uv run monitor.py --help

What's Different from the Last Version?

✅ Added

  • Structured logging integration in monitor.py using kazunoko.log.setup_logger()
  • Comprehensive logging for stdin event processing with sentinel handling
  • Per-event logging with event counters and delayed event waiting
  • TUI event handling logs with panel update tracking
  • Error logging with full exception context via exc_info=True
  • JSON logging to platform-specific directories for monitor analysis
  • Structured context in all logger calls via extra={} dictionaries

🔧 Changed

  • Removed custom setup_logging() function in favor of centralized kazunoko.log.setup_logger()
  • Replaced platformdirs import with kazunoko.log import
  • All logger calls now use structured context with event_num, error, total_events, and operation-specific fields
  • Monitor initialization now calls setup_logger(verbose=False) for consistent logging behavior
  • StdinMonitor event processing includes detailed logging at each stage (parse, callback, completion)

🐛 Fixed

  • None (enhancement release)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing functionality preserved
  • Monitor maintains same command-line interface
  • Logging happens in background without affecting TUI behavior
  • No changes to data output or processing logic
  • Logging is fully transparent to users

Tests Passed

  • ✅ Builds without errors
  • ✅ Monitor script logging initialization verified
  • ✅ Structured logging creates JSON files with proper format
  • ✅ Stdin event processing logs all operations correctly
  • ✅ TUI event handling logs display/update operations
  • ✅ Pre-commit hooks passed (commitizen check)

Release Details

  • Date: 2025-12-24
  • Version: v0.4.6
  • Files Changed: 1 (examples/monitor.py)
  • Commits:
  • 5f03ba7 - feat: integrate kazunoko.log.setup_logger() into monitor.py
  • fb4972b - bump: version 0.4.5 → 0.4.6

Next Steps

  • Extend logging and progress bars to remaining example scripts (fit_thresholds.py, etc.)
  • Consider adding elapsed time tracking to monitor operations for performance analysis
  • Gather user feedback on logging detail level and verbosity
  • Explore monitoring dashboard or analysis tools for real-time JSON log streams