Heatmap Analytics

Relevant source files

The following files were used as context for generating this wiki page:

• src/tabs/heatmap.rs
• src/tabs/base.rs
• src/memory_db.rs
• src/app.rs
• src/main.rs
• src/file_settings.rs

Heatmap Analytics is a specialized visualization module within LogUtil designed to display Nginx request intensity patterns across different temporal dimensions. It provides a color-coded and character-shaded representation of traffic density, allowing administrators to quickly identify peak usage periods and anomalous activity spikes.

The module aggregates raw log data from the global in-memory database and processes it into three distinct granularities: hourly, daily, and weekly distributions. This temporal analysis helps in understanding cyclical traffic patterns and long-term trends that might not be immediately apparent in the real-time Sparkline Analytics.

Sources: src/tabs/heatmap.rs:1-25, README.md:215-220

Architecture and Data Flow

The Heatmap system follows a pull-based architecture where the UI component queries the central data store to generate visualization metrics.

Component Interaction

1. Data Storage: The MemoryDB acts as the single source of truth, storing LogRecord objects indexed by timestamp.
2. Tab Management: The App struct manages the lifecycle of the HeatmapTab, including its instantiation and input routing.
3. Aggregation Logic: The HeatmapTab contains private methods to transform flat log records into frequency maps.
4. Rendering: Using the ratatui framework, the tab renders three parallel tables representing different time buckets.

The diagram above illustrates the flow of data from the in-memory database through the Heatmap processing logic to the TUI display.
Sources: src/tabs/heatmap.rs:36-60, src/memory_db.rs:1-30, src/app.rs:50-75

Data Aggregation and Processing

The system processes LogRecord structures which contain Unix timestamps. The aggregation logic utilizes the chrono crate to bucket these timestamps into specific time ranges.

Temporal Bucketing

• Hourly: Uses Utc.timestamp_opt to extract the hour (0-23) from each record.
• Daily: Formats timestamps into %Y-%m-%d strings for unique day identification.
• Weekly: Utilizes ISO week numbering to group data by week and year.

Intensity Calculation

Intensity is calculated as a floating-point ratio: count / max_count. This normalization ensures that the visualization scales appropriately regardless of total traffic volume.

Granularity	Key Extraction Logic	Sorting Method
Hourly	datetime.hour()	Numeric by hour
Daily	datetime.format("%Y-%m-%d")	Lexicographical by date string
Weekly	datetime.iso_week()	Lexicographical by week/year string

Sources: src/tabs/heatmap.rs:218-285, src/memory_db.rs:10-25

Visualization Components

The Heatmap visualization uses a custom "Intensity Bar" to represent density within the TUI.

Intensity Bar Implementation

The generate_intensity_bar function translates the calculated intensity (0.0 to 1.0) into a 20-character string using Unicode block characters.

// src/tabs/heatmap.rs:287-307
fn generate_intensity_bar(&self, intensity: f64) -> String {
    let bar_length = 20;
    let filled_length = (intensity * bar_length as f64) as usize;
    
    let filled_char = match intensity {
        i if i > 0.8 => "█", // Full block for high density
        i if i > 0.6 => "▓", // Dark shade
        i if i > 0.4 => "▒", // Medium shade
        i if i > 0.2 => "░", // Light shade
        _ => " ",            // Low density
    };
    // ... returns formatted bar string
}

UI Layout

The tab is divided into three equal horizontal segments (33%, 33%, 34%) using Constraint::Percentage. Each segment contains a Table widget with a rounded border. The active panel is highlighted by changing its border color to white (Color::Rgb(255, 255, 255)), while inactive panels remain light green (Color::Rgb(144, 238, 144)).

Sources: src/tabs/heatmap.rs:36-50, src/tabs/heatmap.rs:114-125

User Interaction and Controls

The Heatmap Analytics module supports both keyboard and mouse interaction to navigate between the different temporal views.

Input Mapping

Interaction is handled via the Tab trait implementation in heatmap.rs.

Input	Action
Left / Right	Switch between Hourly (0), Daily (1), and Weekly (2) panels.
Up / Down	Scroll through the list items in the currently active panel.
Tab / t	Switch to the next analytical tab (handled by App).
Shift + Tab	Switch to the previous analytical tab (handled by App).

The sequence diagram shows how the application routes input events to update the Heatmap's internal state before re-rendering.
Sources: src/tabs/heatmap.rs:313-400, src/app.rs:100-150

Configuration and Enabling

Heatmap Analytics is an optional module. It is disabled by default to optimize performance on resource-constrained systems or when analyzing extremely large logs.

Activation Parameters

To enable the module, the --enable-heatmap flag must be passed during startup. This sets the enable_heatmap field in AppConfig, which determines whether the HeatmapTab is added to the TabManager.

Option	Type	Default	Description
--enable-heatmap	Flag	false	Enables the Heatmap Analytics tab in the TUI.
active_panel	Internal State	0	Defaults to Hourly view on load.

Sources: src/main.rs:110-120, src/app.rs:25-45, src/file_settings.rs:110-125

Conclusion

The Heatmap Analytics module provides a robust mechanism for temporal traffic analysis within LogUtil. By leveraging optimized data structures from MemoryDB and providing a clear, shaded visualization of request intensity, it allows users to perform long-term behavioral analysis of their Nginx logs directly from the terminal.

Sources: src/tabs/heatmap.rs, README.md:215-225