Troubleshooting & Debugging

Relevant source files

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

• README.md
• src/main.rs
• src/app.rs
• src/memory_db.rs
• src/file_settings.rs
• src/tabs/security.rs
• src/tabs/errors.rs

LogUtil provides several built-in mechanisms for diagnosing issues related to log parsing, performance degradation, and security threats. Troubleshooting in LogUtil involves a combination of specialized TUI tabs (Security and Errors), debug logging to files, and performance monitoring tools designed to handle large-scale Nginx access logs.

The system is architected to handle real-time data streams while providing historical context. Users can diagnose issues ranging from regex mismatches in log configuration to identifying malicious IP addresses through the integrated threat detection engine.

Sources: README.md:347-380, src/main.rs:114-118

Debug Logging & Console Output

LogUtil includes a dedicated debug mode that allows developers to trace the internal execution flow and capture errors that may occur during the TUI session. This is primarily facilitated through the --log-to-file flag and specialized console output modes.

Application Logging

When the --log-to-file argument is provided, LogUtil initializes a logger that writes to app.log. This file captures critical initialization events and errors encountered by the FileReader or the TUI manager.

Console Reporting Mode

For non-interactive troubleshooting or quick reporting, LogUtil can bypass the TUI entirely to output summarized data directly to the terminal.

CLI Option	Description	Source
--show-urls	Outputs Top N URLs and unique URL counts to console.	src/main.rs:247-259
--show-ips	Outputs Top N IPs and unique IP counts to console.	src/main.rs:261-271
--top	Sets the number of entries for the console report.	src/main.rs:77-78

Error Analysis System

The Errors Tab provides a centralized interface for troubleshooting HTTP-level failures. It categorizes status codes and tracks the distribution of errors across various URLs and IP addresses.

Error Categorization Logic

The system automatically classifies HTTP status codes into functional categories to help pinpoint whether a failure is client-side or server-side.

• Client Errors (400-499): Issues like 404 Not Found or 403 Forbidden.
• Server Errors (500-599): Backend failures or gateway timeouts.
• Other Errors: Non-standard or unclassified status codes.

Sources: src/tabs/errors.rs:49-55

Data Structure for Error Tracking

The MemoryDB utilizes a specialized error_records_cache (a DashMap<u64, bool>) to store IDs of log entries with status codes $\ge 400$, allowing for high-speed retrieval of error statistics without scanning the entire dataset.

Sources: src/memory_db.rs:41-42, src/memory_db.rs:105-108

Security & Threat Debugging

The Security Tab is the primary tool for investigating malicious activity. It identifies patterns indicative of web attacks and allows for real-time inspection of suspicious log entries.

Threat Detection Engine

LogUtil monitors logs for several specific attack signatures:

Attack Type	Monitored Patterns / Indicators	Source
SQL Injection	', union, select, drop, insert, xp_	src/tabs/security.rs:206-210
XSS	<script>, javascript:, alert(, document.cookie	src/tabs/security.rs:213-222
Path Traversal	../, ..\, /etc/, /proc/, windows\	src/tabs/security.rs:225-228
Command Injection	;, |, &, $(, eval(, system(	src/tabs/security.rs:231-234
Brute Force	$> 10$ requests to /login, /auth, /admin, etc.	src/tabs/security.rs:237-255

Security Investigation Workflow

The TUI enables a drill-down workflow for security debugging. Users can select a suspicious IP and enter the Log Detail View (using the d key) to see the raw log line with highlighted threat icons.

Performance & Memory Troubleshooting

LogUtil is designed to handle up to 10,000,000 records but includes safeguards to prevent system exhaustion. If the application becomes sluggish, developers should check the configuration settings.

Memory Management & Eviction

To troubleshoot high memory usage, the MemoryDB implements a FIFO (First-In-First-Out) eviction policy. When the max_records limit is reached, the system removes the oldest half of the records and their associated index entries.

Parsing Issues

The most common troubleshooting scenario is "No match for line" errors, which usually indicate a regex mismatch.

• Custom Regex: Users can provide a custom pattern via --regex.
• Log Verification: Enable --log-to-file and check app.log to see which lines are failing the RegexLite match.
• Interactive Testing: The FileSettings interface allows real-time modification of the Regex Pattern and Date Format before starting the analysis.

Sources: README.md:347-355, src/file_settings.rs:114-124

Troubleshooting Summary Table

Issue	Recommended Action	Source
Parsing Errors	Check regex in FileSettings or via --regex flag.	README.md:348-351
High Resource Usage	Limit initial lines with --count (e.g., 1000).	README.md:358-360
Log Rotation Issues	LogUtil handles truncation; check app.log if monitoring stops.	README.md:338-340
Missing Statistics	Ensure the relevant tab (e.g., --enable-security) is enabled.	src/main.rs:88-106
Clipboard Failures	LogUtil uses arboard; ensure system clipboard dependencies are met.	src/app.rs:135-150

LogUtil provides a robust framework for debugging log-related issues through its interactive TUI and detailed backend indexing. By utilizing the specialized Security and Error tabs alongside application-level debug logging, users can quickly identify both operational failures and security threats within their Nginx environments.

Sources: src/memory_db.rs:392-415, src/app.rs:215-235