Skip to content

USAGE_GUIDE.md

Latest commit

 

History

History
323 lines (246 loc) · 9.47 KB

USAGE_GUIDE.md

File metadata and controls

323 lines (246 loc) · 9.47 KB
Raw

Gonzo Usage Guide

Quick Start

1. Build Everything

make build

2. Test the New TUI Implementation

Option A: Test Mode (Works Anywhere)

# Create some test data
echo '{"level":"INFO","message":"Test log 1"}' > test.log
echo '{"level":"WARN","message":"Test log 2"}' >> test.log
echo '{"level":"ERROR","message":"Test log 3"}' >> test.log

# Test with file input (no TTY required)
./build/gonzo --test-mode -f test.log

# Test with stdin (traditional way)
./build/gonzo --test-mode < test.log

# Test with glob patterns
echo '{"level":"DEBUG","message":"Debug log"}' > debug.log
./build/gonzo --test-mode -f "*.log"

Expected output:

📊 Test Mode Results:

Total lines: 3
Unique words: 6
Unique phrases: 12
Attribute keys: 0

Test completed successfully - no crashes!
Press 'q' to quit or wait 2 seconds for auto-exit.

Option B: Full Interactive TUI (Real Terminal Required)

# Read from files directly
./build/gonzo -f test.log

# Read from multiple files
./build/gonzo -f test.log -f debug.log

# Use glob patterns
./build/gonzo -f "*.log"

# Follow files in real-time (like tail -f)
./build/gonzo -f test.log --follow

# Traditional stdin approach (still works)
cat test.log | ./build/gonzo

# With custom settings
./build/gonzo -f test.log --update-interval=1s --log-buffer=500

# With existing test data
./build/gonzo -f /tmp/test_logs.json

3. Keyboard Shortcuts (Interactive Mode)

Navigation & Control

  • q or Ctrl+C - Clean exit
  • Tab/Shift+Tab - Navigate between sections
  • ↑/↓ or k/j - Select items within sections
  • Enter - Show details for selected item
  • Space - Pause/unpause entire dashboard

Filtering & Search

  • / - Enter regex filter mode
  • s - Search and highlight text in logs
  • Ctrl+F - Open severity filter modal

Severity Filter Modal (Ctrl+f)

  • ↑/↓ or k/j - Navigate severity options
  • Space - Toggle selected severity level on/off
  • Enter - Apply filter and close modal (or quick-select All/None)
  • ESC - Cancel changes and close modal

Modal Features:

  • Select All/None options for quick changes (Enter to apply and close instantly)
  • Individual severity toggles (FATAL, ERROR, WARN, INFO, DEBUG, TRACE, etc.)
  • Color-coded severity levels
  • Real-time active count display

Other Actions

  • f - Open fullscreen log viewer modal
  • c - Toggle Host/Service columns in log view
  • r - Reset all data (manual reset)
  • u/U - Cycle update intervals
  • i - AI analysis (when viewing log details)
  • m - Switch AI model
  • ?/h - Show help

4. Filtering Examples

Using Severity Filter

# Start Gonzo with mixed severity logs
./build/gonzo -f application.log

# In the TUI:
# Quick shortcut:
# 1. Press Ctrl+f to open severity filter modal
# 2. Navigate to "Select None" and press Enter (applies and closes instantly)
# 3. Navigate to "ERROR" and press Space to enable only errors
# 4. Navigate to "FATAL" and press Space to also show fatal logs
# 5. Press Enter to apply filter
# Now only ERROR and FATAL logs will be displayed

Combining Filters

# Start with logs that have various severities and content
./build/gonzo -f /var/log/app.log

# In the TUI:
# 1. Press / to enter regex filter mode, type "database" and press Enter
# 2. Press Ctrl+f to open severity filter
# 3. Navigate to "Select None" and press Enter (quick clear)
# 4. Press Ctrl+f again to reopen modal
# 5. Enable only "ERROR" and "WARN" levels with Space
# 6. Press Enter to apply
# Now you see only database-related errors and warnings

Command Line Options

# TUI specific options
-u, --update-interval=3s         # Dashboard update frequency
-b, --log-buffer=1000            # Maximum log buffer size
-m, --memory-size=10000          # Maximum entries in memory
    --stop-words strings         # Additional stop words to filter from analysis
    --reverse-scroll-wheel       # Reverse scroll wheel direction (natural scrolling)
    --config string              # Config file (default: ~/.gonzo.yaml)

# Web dashboard (Dstl8 Lite)
    --web-port=5718              # Port for the web dashboard
    --web-disabled               # Disable the web dashboard

# Version and help
-v, --version                    # Show version information
-h, --help                       # Show help message

# Commands
gonzo version          # Show detailed version info
gonzo completion bash  # Generate bash completion
gonzo help             # Show help

Stop Words Configuration

Overview

Gonzo filters common English stop words from frequency analysis to focus on meaningful terms. You can add your own custom stop words to filter domain-specific or application-specific terms that aren't relevant to your analysis.

Built-in Stop Words

Gonzo includes 60+ common English stop words by default (the, and, for, are, but, not, etc.). These are automatically filtered from word frequency analysis.

Adding Custom Stop Words

Via Command Line

# Add single custom stop word
./build/gonzo -f app.log --stop-words="debug"

# Add multiple stop words (repeat the flag)
./build/gonzo -f app.log --stop-words="debug" --stop-words="info" --stop-words="warning"

# Or in a single param:
./build/gonzo -f app.log --stop-words="debug,info,warning"

# Filter common log terms
./build/gonzo -f app.log --stop-words="log" --stop-words="message" --stop-words="error"

Via Configuration File

# ~/.config/gonzo/config.yml
stop-words:
  - "debug"
  - "info"
  - "warning"
  - "error"
  - "log"
  - "message"
  - "timestamp"
  - "level"

Via Environment Variable

# Space-separated list
export GONZO_STOP_WORDS="debug info warning error"
./build/gonzo -f app.log

Use Cases

  1. Filter log-specific terms: Remove common logging terms like "log", "message", "level"
  2. Domain-specific filtering: Filter technical terms specific to your application
  3. Noise reduction: Remove high-frequency but low-value terms from analysis
  4. Focus analysis: Highlight actual content by removing structural terms

Examples

# Analyzing web server logs - filter HTTP-related terms
./build/gonzo -f access.log --stop-words="GET" --stop-words="POST" --stop-words="HTTP"

# Analyzing application logs - filter framework noise
./build/gonzo -f app.log --stop-words="springframework" --stop-words="hibernate"

# Analyzing error logs - focus on actual errors
./build/gonzo -f error.log --stop-words="stack" --stop-words="trace" --stop-words="at"

Notes

  • Custom stop words are case-insensitive ("ERROR" and "error" are treated the same)
  • Custom stop words are added to (not replacing) the built-in list
  • Stop words only affect word frequency analysis, not log display or filtering
  • Changes take effect immediately when logs are processed

Reverse Scroll Wheel Configuration

Overview

By default, Gonzo uses traditional scroll wheel behavior (scroll up = content moves up). If you prefer natural/trackpad-style scrolling (scroll up = content moves down), you can enable reverse scroll wheel mode.

Enabling Reverse Scroll

Via Command Line

# Enable reverse scroll wheel
./build/gonzo -f app.log --reverse-scroll-wheel

# Works with all input modes
cat logs.json | ./build/gonzo --reverse-scroll-wheel
./build/gonzo --otlp-enabled --reverse-scroll-wheel

Via Configuration File

# ~/.config/gonzo/config.yml
reverse-scroll-wheel: true

Via Environment Variable

# Set the environment variable
export GONZO_REVERSE_SCROLL_WHEEL=true
./build/gonzo -f app.log

Behavior

When reverse scroll wheel is enabled:

  • Scroll wheel up → Content moves down (viewport scrolls down)
  • Scroll wheel down → Content moves up (viewport scrolls up)

This affects all scrollable areas:

  • Main dashboard log navigation
  • All modal windows (log details, patterns, statistics, etc.)
  • Chat viewport scrolling
  • Model selection
  • Help screen

Use Cases

  • MacOS users: Match trackpad natural scrolling behavior
  • Consistency: Keep same scroll direction across all applications
  • Personal preference: Use whichever feels more intuitive to you

Web Dashboard (Dstl8 Lite)

Gonzo includes an embedded web dashboard that starts automatically alongside the TUI.

Accessing the Dashboard

# Start Gonzo — web dashboard is available at http://localhost:5718
./build/gonzo -f test.log --follow

# Custom port
./build/gonzo -f test.log --web-port=3000

# Disable the web dashboard
./build/gonzo -f test.log --web-disabled

Open http://localhost:5718 in your browser to see:

  • Workspaces - Overview of active log streams with live sparklines
  • Stream Details - Severity distribution, top attributes, pattern analysis, and live log viewer
  • Sentiment Heatmap - Real-time heatmap grouped by pod, namespace, service, host, or deployment
  • Sources - Browse log sources and their dimensions

The dashboard updates in real-time via WebSocket — the same data that powers the TUI.

Building the Web Dashboard

The web dashboard is built with Vite + React + TypeScript and embedded into the Go binary.

# Install dependencies and build (included in make build)
make web-deps
make web-build

# Full build including web dashboard
make build

Supported Integrations