Metrics & Performance Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
Metrics & Performance Monitoring in Kaleidux is a centralized system designed to track the health, resource efficiency, and operational performance of the wallpaper daemon. It encompasses real-time tracking of hardware utilization (CPU and GPU), rendering performance (frame times and transition durations), and resource management (texture pools and cache efficiency).
The system provides developers and users with insights into how the daemon impacts system resources, specifically focusing on hardware-accelerated rendering via WGPU and video playback via GStreamer. It includes proactive leak detection for textures and pipelines, startup timing analysis, and an IPC mechanism for querying the state of connected outputs.
Sources: kaleidux-daemon/src/metrics.rs, kaleidux-daemon/src/monitor.rs, kaleidux-daemon/src/main.rs
Performance Metrics Architecture
The core of the monitoring system is the PerformanceMetrics struct, which utilizes atomic types and thread-safe collections to record data across various asynchronous tasks. It tracks a wide array of statistics ranging from low-level GPU utilization to high-level application uptime.
The diagram shows the relationship between the primary metrics collector and specialized startup timing data.
Sources: kaleidux-daemon/src/metrics.rs:9-64
Data Collection Points
Metrics are gathered from several key operational areas:
- Frame Timing: Records individual frame durations to calculate P50, P95, and P99 percentiles, ensuring smooth visual performance.
- Resource Pools: Tracks hits and misses for the texture pool and file cache to monitor efficiency.
- CPU Attribution: Tracks time spent specifically in the renderer, video decoding, file discovery, and shader compilation.
- Leak Detection: Samples the counts of active textures, pipelines, and channel buffer sizes over time to identify potential memory or handle leaks.
Sources: kaleidux-daemon/src/metrics.rs:11-57, kaleidux-daemon/src/main.rs:885-900
System & Hardware Monitoring
The SystemMonitor component is responsible for periodic polling of system-wide and process-specific resource usage. It leverages the sysinfo crate and direct hardware interface queries (like nvidia-smi or sysfs) to provide a holistic view of the daemon's environment.
GPU Statistics Retrieval
The monitor identifies the hardware vendor and chooses the appropriate method to retrieve utilization data.
| Metric | NVIDIA Source | AMD/Intel Source |
|---|---|---|
| GPU Usage | nvidia-smi (utilization.gpu) | /sys/class/drm/cardX/device/gpu_busy_percent |
| VRAM Used | nvidia-smi (memory.used) | /sys/class/drm/cardX/device/mem_info_vram_used |
| VRAM Total | nvidia-smi (memory.total) | /sys/class/drm/cardX/device/mem_info_vram_total |
Sources: kaleidux-daemon/src/monitor.rs:46-88
Monitoring Flow
The system monitor runs as a background task, updating its internal state and reporting to the centralized metrics system every 10 seconds.
The flow represents the periodic background execution of the resource monitoring task.
Sources: kaleidux-daemon/src/monitor.rs:90-149
Resource Management & Leak Detection
Kaleidux implements specific metrics to detect and prevent common issues in long-running graphical processes, such as resource accumulation and backpressure in communication channels.
Leak Detection Logic
The system analyzes samples of resource counts over 60-second windows. It triggers warnings if:
- Texture Count: Grows by more than 50 units within a minute.
- Pipeline Count: Grows by more than 20 units within a minute.
- Channel Buffers: Queued frames exceed 20 or queued images exceed 4, indicating that the renderer cannot keep up with the producer.
- Texture Pool: Approaches the hard limit of 50 textures.
Sources: kaleidux-daemon/src/metrics.rs:319-382
Cache Monitoring
The file cache system tracks metadata and statistics for all managed wallpapers. Monitoring includes:
- Mtime Validation: Checking if cached metadata matches the current filesystem state.
- Directory Watching: Using
notifyto invalidate cache entries when files are modified, created, or removed.
Sources: kaleidux-daemon/src/cache.rs:60-76, kaleidux-daemon/src/cache.rs:260-288
Operational Reporting
Performance data is exposed through two primary channels: structured logging and IPC queries.
Metrics Summary Log
The daemon periodically (every 10-30 seconds) outputs a comprehensive metrics summary to the logs. This includes:
- Uptime: Formatted duration (e.g.,
1h12m30s). - Memory Growth: Current usage and growth rate in MB/s.
- Frame Stats: Average, P50, P95, and P99 frame times.
- Subsystem CPU: Specific time spent in renderer vs. video decoding.
Sources: kaleidux-daemon/src/metrics.rs:384-428, kaleidux-daemon/src/main.rs:902-913
IPC Status Query
Users can query the status of all active outputs using the kldctl utility, which communicates with the daemon via a Unix socket.
| Request | Response Data | Source |
|---|---|---|
QueryOutputs | Name, Width, Height, Current Wallpaper Path | main.rs:983 |
History | Recently played wallpapers per output | main.rs:1052 |
LoveitList | Multipliers and usage counts for files | main.rs:1044 |
Sources: kaleidux-daemon/src/main.rs:983-1052, kldctl/src/main.rs:300-330
Configuration for Performance
Performance-related behaviors can be tuned via the config.toml file, impacting how the monitoring and rendering systems interact.
[global]
# How often to tick Rhai scripts (seconds) - impacts CPU usage
script-tick-interval = 1
# Default video/image ratio - impacts GPU and VRAM usage
video-ratio = 50
# Transition duration - impacts the period of high GPU activity
transition-time = 1000
Sources: config.example.toml:35-42, kaleidux-daemon/src/orchestration.rs:90-100
Metrics & Performance Monitoring ensures that Kaleidux remains a high-performance daemon by providing deep visibility into the lifecycle of resources and the efficiency of the rendering pipeline. By combining automated leak detection with detailed hardware telemetry, the system enables stable long-term operation on Linux desktops.