Skip to content

v0.3.8 - Monitor Stdin Piping Architecture Fix (2025-12-23)

What Changed?

This release fixes critical issues with stdin piping in the monitor's real-time TUI display. The previous implementation had architectural conflicts between Textual's input handling and the event reading thread. This version implements a robust queue-based architecture with background thread event processing and comprehensive logging for debugging event pipeline issues.

What's New

Queue-Based Event Processing Architecture

What it does: Resolves stdin piping conflicts by reading piped input in a separate background thread before the TUI app starts, passing events through a thread-safe queue. This prevents Textual's keyboard input handler from competing with the event reader for stdin control. The monitor now reliably displays real-time statistics and event data from piped JSONL sources.

How to use it:

# Pipe events into monitor (works reliably now)
uv run kazunoko generate 100 | uv run examples/monitor.py

# Read events from file
cat detector_data.jsonl | uv run examples/monitor.py

# Watch a directory (unchanged)
uv run examples/monitor.py --watch /path/to/data/directory

Features:

  • Queue-Based Event Flow: JSONL events pass through thread-safe Queue from reader thread to UI processor
  • Background Thread Reading: Events are read from stdin BEFORE the TUI starts, avoiding input conflicts
  • Real-time Event Display: New EventStreamPanel shows recent JSONL events alongside statistics
  • Comprehensive Logging: Integrated loguru logging to trace event pipeline execution and identify issues
  • Thread-Safe UI Updates: Proper use of call_from_thread() for safe updates from background threads
  • No Error Spam: Fixed exception handling in queue processing to silence timeout warnings

Installation

Quick Start

# Get the release
git checkout v0.3.8

# Setup
uv sync

# Test stdin piping with monitor
uv run kazunoko generate 50 | uv run examples/monitor.py

# Test directory monitoring
uv run examples/monitor.py --watch examples/20251222_run127

What's Different from the Last Version?

✅ Added

  • Queue-based event processing: Thread-safe Queue for passing events between reader thread and UI
  • _read_piped_input() function: Reads JSONL from stdin in background thread before TUI starts
  • EventStreamPanel widget: Displays recent JSONL events alongside monitor statistics
  • setup_logging() function: Initializes loguru with DEBUG-level logs to platform-specific cache directory
  • Comprehensive logging throughout event pipeline: Trace event reading, parsing, queueing, and UI updates

🔧 Changed

  • StdinMonitor refactored: Changed from direct stdin reading to processing events from a queue
  • Event processing model: Now uses queue.Empty exception handling to silently continue on timeouts
  • Monitor startup sequence: Background stdin reader thread starts BEFORE TUI to avoid input conflicts
  • Logging output: DEBUG logs written to cache directory instead of console (reduces noise)

🐛 Fixed

  • Stdin piping conflicts: Resolved competition between Textual input handling and event reader
  • Missing event displays: Fixed reactive property updates by passing new list objects to trigger re-renders
  • Exception spam in logs: Added explicit except Empty: handling to prevent timeout exception logging
  • UI update safety: Proper thread-safe UI updates using call_from_thread()

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All CLI interfaces remain unchanged (--watch flag still works for directory monitoring)
  • Stdin piping mode is improved, not breaking
  • No changes to library API or existing CLI commands
  • New logging is debug-level and doesn't affect normal operation
  • All existing features continue to work as before

Tests Passed

  • ✅ Builds without errors
  • ✅ Python compilation check passed
  • ✅ Stdin piping works reliably with event parsing
  • ✅ Directory monitoring preserved with --watch flag
  • ✅ Queue-based event processing verified
  • ✅ Real-time statistics update correctly
  • ✅ Recent events display in EventStreamPanel
  • ✅ No error spam in queue timeout handling
  • ✅ Thread-safe UI updates confirmed
  • ✅ Graceful shutdown for both input modes
  • ✅ Pre-commit hooks validation passed

Release Details

  • Date: 2025-12-23
  • Version: v0.3.8
  • Files Changed: 2 (examples/monitor.py + version bump)
  • Key Commits:
  • 5129945 - fix(monitor): resolve stdin piping conflict with textual input handling
  • f9dfc38 - bump: version 0.3.7 → 0.3.8

Next Steps

  • Enhanced error handling and validation for malformed JSON events in the pipeline
  • Real-time event filtering by hit_type or ADC thresholds in monitor UI
  • Export functionality from monitor (save filtered events to JSONL)
  • Integration with measurement workflow for automated data collection
  • Performance optimization for high-frequency event streams (100+ events/sec)