Basic Usage & Examples

Relevant source files

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

• README.md
• src/main.rs
• src/app.rs
• src/file_settings.rs
• src/memory_db.rs
• src/tui_manager.rs

LogUtil is a high-performance, real-time Nginx log analyzer written in Rust. It provides an interactive Terminal User Interface (TUI) to monitor and analyze access logs, offering insights into IP traffic, URL popularity, security threats, and system performance. The tool is designed to handle large log files efficiently through optimized memory management and asynchronous processing.

Sources: README.md:1-15, Cargo.toml:1-10

Getting Started

LogUtil can be executed in two primary modes: Interactive Mode and Direct CLI Mode. When launched without a file path, the application enters an interactive file selector and settings configuration screen. Alternatively, users can specify a file and various flags to bypass the configuration UI.

Execution Flow

The following diagram illustrates how LogUtil handles initial startup and transitions between the configuration phase and the analysis phase.

Interactive Mode

If no file is provided as a command-line argument, LogUtil launches the FileSettings interface. This interface is divided into two main panels: a File Selector and a Configuration panel.

File Selector Features

• Directory Navigation: Users can browse directories, move to parent folders (indicated by ..), and select log files using arrow keys or a mouse.
• Visual Feedback: Icons indicate types: 📁 for directories, 📄 for files, and ⬆️ for parent navigation.
• Double-Click Action: The interface tracks click timing to support double-clicking for immediate analysis.

Settings Configuration

The settings panel allows users to toggle specific analysis modules and parameters before starting the processing engine.

Setting	Type	Description
Count	Number	Lines to read (0 = tail, -1 = all).
Regex Pattern	Regex	Pattern used to parse log lines.
Date Format	Text	Format for parsing timestamps.
Top N	Number	Number of top entries to display in lists.
Enable Security	Boolean	Toggles attack pattern detection.
Enable Performance	Boolean	Toggles response time monitoring.
Enable Heatmap	Boolean	Toggles time-distribution visualization.

Sources: src/file_settings.rs:104-165, src/file_settings.rs:260-310

CLI Command Examples

For automated use or power users, LogUtil supports direct command-line arguments.

Basic Monitoring

To monitor a log file in real-time starting from the end of the file:

logutil /var/log/nginx/access.log

Sources: README.md:195-200

Advanced Analysis

To analyze the entire history of a log file with all advanced features enabled:

logutil access.log --count=-1 --enable-security --enable-performance --enable-heatmap --enable-sparkline

Sources: README.md:165-175, src/main.rs:60-100

Console-Only Output

LogUtil can output statistics directly to the console without launching the TUI:

logutil access.log --show-urls --top=20

Sources: src/main.rs:215-245, README.md:245-255

Main Interface Navigation

Once analysis starts, the application uses a TabManager to handle multiple views. Each tab focuses on a specific aspect of the log data.

Keyboard Shortcuts

Key	Action
Tab / t	Switch to the next tab.
Shift+Tab / T	Switch to the previous tab.
q / Ctrl+C	Quit the application.
Enter	Copy the selected item (IP or URL) to the clipboard.
Left/Right	Switch between panels within a tab (e.g., IPs vs URLs).
Up/Down	Navigate through lists.

Sources: src/app.rs:114-175, README.md:115-135

Data Flow Architecture

LogUtil uses a background thread to monitor files and update a global in-memory database (GLOBAL_DB), which the UI thread then reads to render frames.

Feature Summary

• Real-time Tail: Automatically processes new log entries as they are written to disk.
• Memory Efficiency: Implements an eviction policy (evict_old_records) that keeps the database within limits (default 10M records) to prevent OOM.
• Advanced Threat Detection: The Security tab identifies SQL Injection, XSS, and Path Traversal patterns by scanning log lines against known signatures.
• Performance Profiling: Tracks average, min, and max response times, highlighting "slow" requests based on configurable thresholds.

Sources: src/memory_db.rs:115-130, src/tabs/security.rs:225-260, README.md:25-50