Basic Usage

Master the essential Gonzo usage patterns. This guide covers the most common ways to analyze logs and the fundamental workflows you'll use daily.

New to Gonzo? Complete the Quick Start Tutorial first for a hands-on introduction to the interface.

Core Usage Patterns

Reading from Files

The most common way to use Gonzo is analyzing log files directly:

# Analyze a single log file
gonzo -f application.log

# Analyze multiple specific files
gonzo -f application.log -f error.log -f debug.log

# Use glob patterns for multiple files
gonzo -f "/var/log/*.log"
gonzo -f "/var/log/app/*.log" -f "/var/log/nginx/*.log"

Single File

Perfect for focused analysis of one application or service:

gonzo -f /var/log/myapp.log

Best for:

• Debugging specific applications

• Analyzing archived log files

• Initial investigation of issues

Multiple Files

Combine logs from related services for comprehensive analysis:

gonzo -f api.log -f database.log -f cache.log

Best for:

• Multi-service debugging

• Correlating events across systems

• Full-stack troubleshooting

Glob Patterns

Automatically include all matching files:

gonzo -f "/var/log/myapp-*.log"
gonzo -f "/logs/**/*.log"

Best for:

• Rotated log files (app.log, app.log.1, etc.)

• Directory-based log organization

• Dynamic file discovery

Real-Time Log Following

Monitor logs as they grow, similar to tail -f:

# Follow a single file
gonzo -f /var/log/app.log --follow

# Follow multiple files
gonzo -f "/var/log/*.log" --follow

# Follow with glob patterns
gonzo -f "/var/log/app-*.log" --follow

Pro Tip: Use Space to pause the live feed while keeping the data flowing in the background. Press Space again to resume auto-scrolling.

Stdin Processing (Piping)

Gonzo excels at processing log streams from other commands:

Basic Piping

# Analyze existing logs
cat application.log | gonzo

# Process compressed logs
zcat app.log.gz | gonzo
gunzip -c logs.gz | gonzo

Live Streaming

# Stream system logs
tail -f /var/log/syslog | gonzo

# Follow multiple files
tail -f /var/log/*.log | gonzo

# Use multitail for complex scenarios
multitail -f /var/log/app.log /var/log/error.log | gonzo

Container Logs

# Docker container logs
docker logs -f my-container 2>&1 | gonzo

# Multiple containers
docker logs -f container1 container2 2>&1 | gonzo

# Docker Compose services
docker-compose logs -f | gonzo

Kubernetes Logs

# Pod logs
kubectl logs -f deployment/my-app | gonzo

# Multiple pods
kubectl logs -f -l app=backend | gonzo

# With stern (if installed) - get logs from all pods, all namespaces
stern . --all-namespaces --output json | gonzo

Command-Line Options

Essential Flags

Flag	Description	Example
-h, --help	Gonzo help	-h, --help
-f, --file	Specify log files or patterns	gonzo -f app.log
--follow	Follow files like tail -f	gonzo -f app.log --follow
-u, --update-interval	Dashboard refresh rate	gonzo -f app.log -u 2s
-b, --log-buffer	Maximum log entries to keep	gonzo -f app.log -b 5000
--ai-model	AI model for analysis	gonzo -f app.log --ai-model="gpt-4"

Buffer and Performance Tuning

Optimize Gonzo for your log volume and system resources:

# Large log files - increase buffer
gonzo -f huge.log --log-buffer=10000

# High-frequency logs - slower updates
gonzo -f busy.log --update-interval=5s

# Memory-constrained systems
gonzo -f app.log --memory-size=5000 --log-buffer=1000

# Performance monitoring
gonzo -f app.log --update-interval=500ms --log-buffer=2000

Working with Different Log Formats

Gonzo automatically detects and handles multiple log formats, including Custom Formats. Use the Quick Start section to try out a few of the supported log formats.

JSON Logs

{"timestamp":"2024-01-15T10:30:00Z","level":"error","service":"api","message":"Database timeout"}

Features:

• ✅ Automatic field extraction

• ✅ Structured attribute display

• ✅ Nested object support

• ✅ Array handling

Logfmt Format

time=2024-01-15T10:30:00Z level=error service=api msg="Database timeout" duration=30.5s

Features:

• ✅ Key-value pair extraction

• ✅ Quoted value support

• ✅ Numeric type detection

• ✅ Space and special character handling

Plain Text Logs

2024-01-15 10:30:00 [ERROR] api: Database timeout after 30.5 seconds

Features:

• ✅ Pattern-based level detection

• ✅ Timestamp recognition

• ✅ Service name extraction

• ✅ Word frequency analysis

Format Detection: Gonzo automatically detects the format of each log entry. You can mix different formats in the same analysis session.

Essential Workflows

Debugging Application Issues

# 1. Start with error-level filtering
gonzo -f app.log --follow
# Press '/' and type: error|Error

# 2. Examine patterns in Counts panel
# Press Enter on Counts panel for detailed analysis

# 3. Use AI for insights (if configured)
# Press 'i' in any log detail view

Performance Monitoring

# Monitor multiple services
gonzo -f "/var/log/app-*.log" --follow

# Focus on warnings and errors
# Use filtering press '/': warn|error

# Track response times and patterns
# Watch Word Frequency panel for performance keywords

System Health Monitoring

# Monitor system logs
sudo gonzo -f "/var/log/syslog" --follow

# Multi-service monitoring
gonzo -f "/var/log/*.log" --follow

# Filter for critical events
# Use regex in filter press '/': fail|error|critical|timeout

Navigation Essentials

Panel Navigation

Key Shortcuts for Daily Use

Key	Action	Try This
Tab / Shift+Tab	Switch between panels	Navigate around the 2x2 grid
↑/↓ or k/j	Move up/down in lists	Navigate through log entries
Enter	View details	Press on a log entry or the Counts panel
Space	Pause/unpause dashboard	Freeze the display to examine data
/	Enter filter mode	Type regex patterns to filter logs
s	Search/highlight	Search and highlight text in logs
f	Enter full screen log viewer	Fill your terminal with full screen log viewer
Escape	Close modal/exit filter mode	Close modal/exit filter mode
q	Quit Gonzo	Exit the application
?/h	Show help	Show help

Configuration for Daily Use

Environment Variables

Set these for consistent behavior:

# Add to your ~/.bashrc or ~/.zshrc
export GONZO_UPDATE_INTERVAL="2s"
export GONZO_LOG_BUFFER="2000"
export GONZO_MEMORY_SIZE="15000"

# AI configuration
export OPENAI_API_KEY="your-key-here"

Config File Setup

Create ~/.config/gonzo/config.yml for persistent settings:

# Default file patterns
files:
  - "/var/log/app.log"
  - "/var/log/error.log"

# Enable real-time following
follow: true

# Performance settings
update-interval: 2s
log-buffer: 2000
memory-size: 15000

# AI model preference
ai-model: "gpt-4"

Common Patterns by Use Case

Web Application Monitoring

# Monitor web server and application logs
gonzo -f /var/log/nginx/access.log -f /var/log/app/error.log --follow

# Filter for HTTP errors
# Regex: (4[0-9]{2}|5[0-9]{2}|error)

Microservices Debugging

# Monitor all service logs
gonzo -f "/var/log/service-*.log" --follow

# Focus on service communication
# Filter: (http|api|request|response)

Database Troubleshooting

# Monitor database logs
gonzo -f /var/log/postgresql/postgresql.log --follow

# Look for performance issues  
# Filter: (slow|timeout|deadlock|error)

CI/CD Pipeline Analysis

# Analyze build logs
gonzo -f build.log

# Monitor deployment logs
kubectl logs -f deployment/app | gonzo

# Filter for failures
# Regex: (fail|error|exit)

Best Practices

🎯 Efficient Filtering

• Start broad, then narrow down with specific filters

• Use regex for pattern matching: *(api|web)

• Combine severity with keywords: *error.*database

⚡ Performance Optimization

• Use --follow only when needed for real-time analysis

• Adjust buffer sizes based on log volume

• Filter early to reduce processing overhead

🔍 Effective Analysis

• Use the Counts panel for pattern recognition

• Leverage AI analysis for complex issues

• Pause the feed when examining specific entries

🛠️ Workflow Integration

• Create shell aliases for common commands

• Use config files for consistent settings

• Combine with other tools (stern, kubectl, docker)

Troubleshooting Common Issues

File Access Problems

# Permission denied
sudo gonzo -f /var/log/secure.log

# File not found
gonzo -f "/var/log/app*.log"  # Use quotes with wildcards

Performance Issues

# Large files - increase buffer and slow updates
gonzo -f huge.log --log-buffer=10000 --update-interval=5s

# High-frequency logs - reduce memory usage
gonzo -f busy.log --memory-size=5000

Display Issues

# Terminal too small
# Resize terminal or use minimal view

# Colors not showing
unset NO_COLOR
export TERM=xterm-256color

What's Next?

Now that you've mastered basic usage, explore these advanced features:

• Interface Overview - Deep dive into each panel

• Log Input Methods - OTLP, streaming, and advanced sources

• Filtering & Search - Advanced filtering techniques

• Configuration - Customize for your workflow

---

You're now ready to use Gonzo effectively for daily log analysis! 🚀 These patterns will handle 90% of your log analysis needs.