Interface Overview

Gonzo's terminal interface is designed for efficiency and insight. The k9s-inspired 2x2 grid layout provides four specialized views of your log data, each optimized for different aspects of log analysis.

The 2x2 Grid Layout

┌─────────────────────┬─────────────────────┐
│                     │                     │
│    LOG VIEWER       │  WORD FREQUENCY     │
│   (Top Left)        │   (Top Right)       │
│                     │                     │
│  📄 Real-time logs  │  📊 Keyword counts  │
│  Color-coded by     │  Most frequent      │
│  severity level     │  terms ranked       │
│                     │                     │
├─────────────────────┼─────────────────────┤
│                     │                     │
│   ATTRIBUTES        │      COUNTS         │
│  (Bottom Left)      │  (Bottom Right)     │
│                     │                     │
│  🏷️ Structured data │  📈 Analytics hub   │
│  Key-value pairs    │  Patterns & trends  │
│  from logs          │  Time-series data   │
│                     │                     │
└─────────────────────┴─────────────────────┘

Navigation Tip: Use Tab and Shift+Tab to move between panels, or click directly on any panel to focus it.

Panel 1: Log Viewer (Top Left)

The Log Viewer is your primary interface for examining individual log entries in real-time.

What You'll See

┌─ LOG VIEWER ─────────────────────────┐
│ 2024-01-15 10:30:00 [INFO] web-api  │ ← Timestamp, level, service
│ 2024-01-15 10:30:05 [ERROR] web-api │ ← Color-coded by severity
│ 2024-01-15 10:30:10 [WARN] auth     │ ← Auto-scroll with new entries
│ 2024-01-15 10:30:15 [INFO] web-api  │
│ 2024-01-15 10:30:20 [ERROR] db      │
│ ▼ More logs below...                │ ← Scroll indicator
└─────────────────────────────────────┘

Color Coding

Gonzo uses intuitive color coding to help you quickly identify issues:

Level	Color	When You'll See It
🔴 ERROR	Red/Bright Red	Critical failures, exceptions, system errors
🟡 WARN	Yellow/Orange	Warnings, deprecations, potential issues
🔵 INFO	Blue/Cyan	General information, successful operations
⚪ DEBUG	White/Gray	Detailed debugging information
🟣 TRACE	Purple/Magenta	Verbose tracing information

Features

• Auto-scroll: New logs automatically appear at the bottom

• Smart pause: Auto-scroll stops when you navigate up, resumes when you go to bottom

• Intelligent parsing: Automatic detection of timestamps, levels, and services

• Overflow handling: Maintains performance with high-volume log streams

• Selection highlighting: Current entry is highlighted for easy reference

Navigation

Key	Action	Description
↑/↓ or k/j	Move up/down	Navigate through log entries
Page Up/Down	Jump by pages	Navigate quickly through large sets
Home	Jump to top	Go to oldest log in buffer
End	Jump to bottom	Go to newest logs (resumes auto-scroll)
Enter	View details	Open detailed modal for selected log

Real-time Mode

When following logs (--follow):

• New entries automatically scroll into view

• Pauses auto-scroll when you navigate up

• Resume by pressing End or scrolling to bottom

• Use Space to globally pause/unpause the entire dashboard

File Analysis Mode

Panel 2: Word Frequency (Top Right)

The Word Frequency panel shows the most common words and terms across all your logs.

What You'll See

┌─ WORD FREQUENCY ─────────────────────┐
│ error        (1,247) ████████████████ │ ← Most frequent term
│ timeout      (892)   ████████████     │
│ database     (654)   ████████         │
│ connection   (521)   ██████           │
│ user         (445)   █████            │
│ login        (398)   █████            │
│ failed       (234)   ███              │
│ success      (198)   ██               │
│ request      (156)   ██               │
│ response     (134)   █                │
└─────────────────────────────────────┘

Features

• Real-time updates: Frequency counts update as new logs arrive

• Visual bars: Bar length represents relative frequency

• Automatic filtering: Ignores common words like "the", "and", "of"

• Case insensitive: "Error" and "error" are counted together

• Memory efficient: Configurable limit on tracked words

Use Cases

Problem Identification

Spot issues quickly:

• High frequency of "error", "fail", "timeout"

• Unusual spikes in specific service names

• New error messages appearing in top words

System Health

Service Analysis

Interaction

• Click on words: Filter logs to show only entries containing that word

• Arrow navigation: Browse through the frequency list

• Enter: Apply word as a filter to the Log Viewer

Panel 3: Attributes (Bottom Left)

The Attributes panel displays structured data extracted from your logs, perfect for JSON and logfmt formats.

What You'll See

┌─ ATTRIBUTES ─────────────────────────┐
│ service      = "web-api"             │ ← Key-value pairs
│ level        = "error"               │
│ user_id      = "12345"               │ ← Extracted from JSON/logfmt
│ duration     = "30.5s"               │
│ method       = "POST"                │
│ status_code  = "500"                 │
│ endpoint     = "/api/users"          │
│ error        = "database timeout"    │
│ trace_id     = "abc123def456"        │
│ timestamp    = "2024-01-15T10:30:00" │
└─────────────────────────────────────┘

Supported Formats

JSON Logs

{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "error",
  "service": "web-api",
  "message": "Database timeout",
  "user_id": "12345",
  "duration": 30.5,
  "trace_id": "abc123def456"
}

Features:

• Nested object support

• Array handling

• Type preservation (strings, numbers, booleans)

• Automatic flattening of complex structures

Logfmt Format

Plain Text

Features

• Smart extraction: Automatically detects and parses structured data

• Type awareness: Preserves data types (strings, numbers, booleans)

• Nested support: Handles complex JSON objects and arrays

• Real-time updates: Shows attributes from the currently selected log entry

• Search integration: Click attributes to filter logs

Navigation

• ↑/↓ arrows: Browse through attribute list

• Click attributes: Use as search terms

• Copy-friendly: Easily copy attribute names and values

Panel 4: Counts (Bottom Right)

The Counts panel is your analytics hub, providing insights into log patterns, severity distribution, and trends.

What You'll See

┌─ COUNTS ─────────────────────────────┐
│ Severity Distribution:               │
│ ERROR  █████████████████████   (45%) │
│ WARN   ██████████████          (30%) │
│ INFO   ███████                 (20%) │
│ DEBUG  ██                       (5%) │
│                                      │
│ Total Entries: 2,847                 │
│ Time Span: 2h 15m                    │
│ Entries/min: 21.2                    │
│                                      │
│ Press Enter for detailed analysis... │
└─────────────────────────────────────┘

Key Metrics

Metric	Description	What It Tells You
Severity Distribution	Percentage breakdown by log level	Overall system health
Total Entries	Count of all processed log entries	Volume of activity
Time Span	Duration from first to last log	Analysis window
Entries/min	Average log frequency	System activity level
Pattern Count	Number of identified patterns	Log complexity

Detailed Analysis Modal

Press Enter on the Counts panel to open the comprehensive analysis modal:

┌─ LOG ANALYSIS (Press ESC to close) ──────────────────────────────┐
│                                                                  │
│ Time-Series Heatmap (60-minute rolling window):                  │
│ ┌────────────────────────────────────────────────────────────┐   │
│ │Time: 60  50  40  30  20  10  0 (minutes ago)              │   │  
│ │ERROR ████░░██████░░░░████████████████ High intensity      │   │
│ │WARN  ░░██████░░████░░░░██████░░░░░░░░ Medium intensity    │   │
│ │INFO  ░░░░░░░░░░░░░░░░████░░░░░░░░░░░░ Low intensity       │   │
│ │DEBUG ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Minimal activity    │   │
│ └────────────────────────────────────────────────────────────┘   │
│                                                                  │
│ Top 3 Patterns by Severity:                                     │
│ ┌────────────────────────────────────────────────────────────┐   │
│ │ ERROR:                                                     │   │
│ │ 1. Database connection timeout (247 occurrences)          │   │
│ │ 2. User authentication failed (156 occurrences)           │   │
│ │ 3. API rate limit exceeded (89 occurrences)               │   │
│ │                                                            │   │
│ │ WARN:                                                      │   │
│ │ 1. Slow query detected (324 occurrences)                  │   │
│ │ 2. Memory usage high (198 occurrences)                    │   │
│ │ 3. Cache miss rate elevated (156 occurrences)             │   │
│ └────────────────────────────────────────────────────────────┘   │
│                                                                  │
│ Service Distribution:                                            │
│ web-api: 1,247 entries (44%)  database: 892 entries (31%)      │
│ auth: 654 entries (23%)       cache: 54 entries (2%)           │
│                                                                  │
│ Navigation: ↑/↓ Scroll, Mouse Wheel, ESC to close               │
└──────────────────────────────────────────────────────────────────┘

Advanced Features

Heatmap Visualization

Time-series heatmap shows:

• 60-minute rolling window

• Severity levels vs. time

• 1-minute resolution buckets

• ASCII intensity indicators (░▒▓█)

• Real-time updates as logs arrive

Best for:

• Identifying when problems occurred

• Spotting patterns over time

• Correlating events across severity levels

Pattern Detection

Service Analysis

Global Interface Features

Status Indicators

┌─ Gonzo v1.0.0 ─────── Status: LIVE ── Paused: No ── AI: Ready ──┐
│                                                                  │
│ [Active filter: level.*error] [Update: 1.2s] [Entries: 1,247]   │

Indicator	Meaning	States
Status	Data source state	LIVE, FILE, STDIN, OTLP
Paused	Global pause state	Yes, No
AI	AI analysis availability	Ready, Disabled, Error
Active filter	Current regex filter	Shows active pattern
Update	Last refresh time	Real-time update indicator
Entries	Total log count	Running total

Visual Cues

• Scrollbars: Indicate more content available

• Selection highlighting: Current focused item

• Color consistency: Same colors across all panels

• Progress indicators: Loading states and progress

• Overflow indicators: "..." when content is truncated

Customization & Settings

Display Options

Key	Action	Effect
c	Toggle columns	Show/hide Host and Service columns
u/U	Cycle update intervals	Adjust refresh rate (1s, 2s, 5s, 10s)
r	Reset data	Clear all panels and restart analysis

Performance Tuning

The interface adapts to your system and log volume:

• Buffer management: Automatically maintains optimal memory usage

• Update throttling: Adjusts refresh rate based on log frequency

• Render optimization: Only redraws changed content

• Memory limits: Configurable limits prevent resource exhaustion

Best Practices

🎯 Efficient Usage

1. Start with Counts panel - Get overview before diving into details

2. Use Word Frequency for quick insights - Spot problems immediately

3. Leverage color coding - Train your eye to spot red (errors) quickly

4. Master panel switching - Tab through panels efficiently

🔍 Effective Analysis

1. Pause when needed - Use Space to freeze the view for examination

2. Filter progressively - Start broad, then narrow down

3. Use attributes for correlation - Click attributes to find related logs

4. Explore patterns - Press Enter on Counts for deep analysis

⚡ Performance Tips

1. Adjust buffer sizes - Increase for better history, decrease for performance

2. Use appropriate update intervals - Slower updates for high-volume logs

3. Filter early - Reduce processing overhead with targeted filters

4. Monitor memory usage - Reset data periodically for long-running sessions

What's Next?

Now that you understand the interface, explore these guides for deeper functionality:

• Navigation & Controls - Master all keyboard shortcuts and mouse controls

• Log Input Methods - Advanced ways to feed data into Gonzo

• Filtering & Search - Advanced search techniques and regex patterns

• AI Integration - Add intelligent analysis to your workflow

---

You now understand Gonzo's interface design! 🚀 The 2x2 layout gives you four different perspectives on your log data, each optimized for specific analysis tasks.