Python Analysis Tools
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Python Analysis Tools within the Kaleidux project serve as post-processing utilities designed to parse, analyze, and visualize the operational behavior of the wallpaper daemon. These tools primarily focus on interpreting log files generated by kaleidux-daemon to extract timing data, verify interval consistency, and monitor system performance over time.
While the core daemon is implemented in Rust for high performance, these Python scripts provide a flexible way to perform data science tasks on execution logs. This is particularly useful for debugging transition timings, verifying scheduled changes across multiple monitors, and identifying potential regressions in the renderer or orchestration logic.
Sources: analyze_intervals.py:1-24, README.md:95-99, kaleidux-daemon/src/main.rs:252-259
Interval Analysis Logic
The primary function of the analysis tools is to calculate the delta between scheduled events. The tools use regular expressions to scan for specific log patterns indicating that the daemon has scheduled a content change for a specific output.
Log Parsing Mechanism
The analysis script targets log files (e.g., kaleidux-daemon-2026-01-08_07-02-25.log) and extracts two main pieces of information:
- Timestamp: A high-precision ISO-8601-like string including milliseconds.
- Output Identifier: The name of the monitor or display output for which the change was scheduled.
The script maintains a stateful dictionary (last_time) to track the previous timestamp for each unique output, allowing it to calculate the precise seconds elapsed between consecutive "Scheduled next change" events.
Sources: analyze_intervals.py:6-24
Data Flow Diagram
The following diagram illustrates how raw log data is transformed into interval analysis:
This diagram shows the sequential processing of log lines to generate a text-based report of timing intervals.
Sources: analyze_intervals.py:6-24
Component Overview
Core Functions and Patterns
| Component | Implementation | Description |
|---|---|---|
| Log Scanner | re.compile(r"(\d{4}-...Scheduled next change for (\S+)") | Identifies relevant scheduling lines in daemon logs. |
| Timestamp Converter | datetime.strptime(ts_str, "%Y-%m-%d %H:%M:%S.%f") | Converts log strings into Python objects for math. |
| Output State Tracker | last_time = {} | Tracks the history of events per monitor name. |
| Results Generator | out.write(f"{output}: {delta:.3f}s\n") | Exports processed timing data to external files. |
Sources: analyze_intervals.py:6-24
Relationship with Daemon Logging
The Python tools are dependent on the logging configuration defined in the Rust daemon. The daemon supports four levels of logging (1=WARN, 2=INFO, 3=DEBUG, 4=TRACE), which determine the verbosity of the data available for analysis. Logs are typically stored in the user's config directory under kaleidux/logs/.
Sources: kaleidux-daemon/src/main.rs:252-268, README.md:95-99
Integration with Metrics System
While the Python tools handle external log analysis, they complement the internal PerformanceMetrics system within the Rust daemon. The daemon records various metrics that eventually appear in the logs parsed by the Python scripts:
- Startup Metrics: Durations for GStreamer and WGPU initialization.
- Frame Timing: Average and percentile (p50, p95, p99) frame times.
- Resource Usage: Memory growth rates and GPU utilization.
The Python scripts can be extended to parse the [METRICS] and [STARTUP] log tags generated by the log_summary() and log_startup_summary() functions in the Rust source.
Sources: kaleidux-daemon/src/metrics.rs:188-215, kaleidux-daemon/src/metrics.rs:431-470
Conclusion
Python Analysis Tools provide an essential diagnostic layer for Kaleidux developers. By transforming raw text logs into structured interval data, these tools ensure that the "Independent", "Synchronized", or "Grouped" monitor behaviors defined in the orchestration layer are executing with the timing precision required for a high-performance wallpaper daemon.
Sources: PROJECT_STANDARDS.md:387-392, analyze_intervals.py:1-24