Getting Started

Welcome to Gonzo! Get up and running with powerful log analysis in under 10 minutes. This section will take you from installation to analyzing your first logs with confidence.

What is Gonzo?

Gonzo is an open source Go-based TUI (Terminal User Interface) log analysis tool that transforms how you understand and debug your applications. Inspired by k9s, Gonzo provides:

• 🔍 Real-time log analysis with beautiful terminal charts

• 🤖 AI-powered insights to identify patterns and anomalies

• 📊 Multiple data views in an intuitive 2x2 grid layout

• 🚀 Live streaming from files, stdin, or OpenTelemetry

• 🎯 Smart filtering with regex support and severity tracking

Perfect for: Application debugging, system monitoring, microservice analysis, and any scenario where you need to quickly understand what's happening in your logs.

Your Journey to Log Analysis Mastery

This Getting Started section is designed as a progressive learning path. Each guide builds on the previous one:

Installation → Quick Start → Basic Usage → Ready for Advanced Features!
     ⏱️ 2-3 min     ⏱️ 10 min      ⏱️ 15 min         🚀 You're ready!

Guide Overview

Installation

Get Gonzo installed and ready to use

Multiple installation methods to fit your environment:

• Go install (recommended for developers)

• Homebrew (easiest for macOS/Linux)

• Binary downloads (works everywhere)

• Build from source (for contributors and latest features)

• Shell completion setup for better CLI experience

What you'll have: A working gonzo command ready to analyze logs Time required: 2-5 minutes Prerequisites: None

---

Quick Start

Your first log analysis in 5 minutes

Hands-on tutorial that gets you analyzing logs immediately:

• Create sample log files to work with

• Launch Gonzo and understand the interface

• Learn essential navigation and shortcuts

• Try filtering and real-time log following

• See AI analysis in action

What you'll have: Practical experience with Gonzo's core features Time required: 10-15 minutes Prerequisites: Gonzo installation complete

---

Basic Usage

Master the fundamental usage patterns

Comprehensive coverage of daily Gonzo workflows:

• File analysis patterns (single, multiple, glob)

• Real-time log following with --follow

• Stdin processing and piping from other tools

• Working with different log formats (JSON, logfmt, plain text)

• Common command-line options and configurations

What you'll have: Solid foundation for using Gonzo in real scenarios Time required: 15-20 minutes Prerequisites: Quick Start completion

Success Milestones

As you work through Getting Started, you'll achieve these key milestones:

After Installation

✅ You can run Gonzo

gonzo --version

✅ Shell completion works (optional but recommended)

gonzo <tab><tab>  # Shows available commands

✅ Ready for your first analysis

After Quick Start

✅ You understand the 2x2+1 interface

• Top words (top-left) top words appearing in logs

• Attributes (top-right) for structured data

• Log Patterns (middle-right) for common terms/phrases in the logs

• Log Counts (middle-right) for serverity over time and heatmap

• Log Viewer (bottom) for real-time logs

✅ You can navigate effectively

• Switch panels with Tab

• Pause/unpause with Space

• Filter logs with /

✅ You've seen AI analysis in action (if configured)

After Basic Usage

✅ You know all the input methods

• File analysis: gonzo -f app.log

• Real-time following: gonzo -f app.log --follow

• Piping: cat logs | gonzo

✅ You understand log format support

• JSON logs with automatic field extraction

• Logfmt with key-value parsing

• Plain text with intelligent parsing

✅ You can handle real scenarios

• Multiple log files

• High-volume log streams

• Integration with existing tools

Choose Your Path

Different users have different needs. Pick the approach that matches your situation:

🚀 Fast Track (15 minutes total)

Just want to start analyzing logs quickly?

1. Installation - Use Go install or Homebrew

2. Quick Start - Skip to "Your First Log Analysis"

3. Start analyzing your own logs immediately

Best for: Experienced developers who learn by doing

📚 Complete Path (30-40 minutes total)

Want to understand everything thoroughly?

1. Installation - Try multiple methods, set up shell completion

2. Quick Start - Work through all examples and scenarios

3. Basic Usage - Read all sections, try different patterns

Best for: Users new to log analysis tools or those who prefer comprehensive understanding

🔧 Integration Focus (20-30 minutes total)

Need to integrate with existing systems?

1. Installation - Focus on your deployment method

2. Basic Usage - Emphasize stdin processing and piping

3. Quick Start - Try integration examples

4. Jump to Integration Examples next

Best for: DevOps engineers and system administrators

Essential Commands to Remember

By the end of Getting Started, you'll know these core patterns:

# Basic file analysis
gonzo -f application.log

# Real-time monitoring  
gonzo -f /var/log/app.log --follow

# Analyzing multiple sources
gonzo -f api.log -f db.log -f cache.log

# Piping from other tools
kubectl logs -f deployment/my-app | gonzo
docker logs -f my-container | gonzo
tail -f /var/log/syslog | gonzo

# With AI analysis (when configured)
gonzo -f app.log --ai-model="gpt-4"

Common First-Time Scenarios

Here are real-world scenarios you can tackle right after Getting Started:

Application Debugging

Scenario: Your web application is throwing errors

# Monitor application logs in real-time
gonzo -f /var/log/myapp.log --follow

# Filter for errors only
# Press '/' then type: Error|error

You'll quickly see:

• Error frequency and patterns

• Most common error messages

• When errors are occurring (time patterns)

System Monitoring

Scenario: System performance seems slow

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

# Look for performance indicators
# Filter with: (slow|timeout|memory|cpu)

You'll identify:

• Resource usage warnings

• Service startup/shutdown patterns

• Hardware or driver issues

Container Troubleshooting

Scenario: Docker container keeps crashing

# Analyze container logs
docker logs my-container | gonzo

# For live monitoring
docker logs -f my-container 2>&1 | gonzo

You'll discover:

• Crash patterns and frequency

• Error messages before failures

• Resource exhaustion indicators

Troubleshooting Your First Experience

Installation issues?

• Check Installation troubleshooting

• Verify Go version (1.21+ required)

• Try alternative installation methods

Gonzo not starting?

• Test with simple input: echo "test log" | gonzo

• Check terminal compatibility (UTF-8 support required)

• Verify file permissions for log files

Interface looks wrong?

• Ensure terminal is large enough (minimum 80x24)

• Check for NO_COLOR environment variable

• Try resizing terminal window

Not seeing logs?

• Verify file paths are correct

• Check file permissions (ls -la logfile.log)

• Try with absolute paths instead of relative

What Happens Next?

After completing Getting Started, you'll be ready to dive deeper:

Immediate Next Steps

• User Guide - Master the interface and advanced navigation

• Configuration - Customize Gonzo for your workflow

• Integration Examples - Real-world usage patterns

Advanced Features

• AI Integration - Set up intelligent log analysis

• Log Analysis - Advanced pattern detection and insights

• OTLP Integration - OpenTelemetry log collection

Community & Support

• Contributing - Help improve Gonzo

• GitHub Discussions - Ask questions and share tips

• GitHub Issues - Report bugs or request features

Success Tips

🎯 Start small - Begin with a single log file you're familiar with 📚 Follow the order - Each guide builds on the previous one 🔄 Practice regularly - Try Gonzo with different types of logs ❓ Ask questions - Use GitHub Discussions if you get stuck 🚀 Share your experience - Help others by sharing tips and patterns

---

Ready to transform your log analysis workflow? 🚀

Start with Installation and you'll be analyzing logs like a pro in no time!