Quick Start

Get up and running with Gonzo in under 5 minutes! This tutorial will walk you through your first log analysis session.

Prerequisites: Make sure you have Gonzo installed. If not, check the Installation Guide first.

Your First Log Analysis

Let's start with a simple example using sample log data.

Step 1: Create Sample Logs

First, let's create some sample log data to analyze:

JSON Logs

# Create a sample JSON log file
cat > sample.log << EOF
{"timestamp":"2024-01-15T10:30:00Z","level":"info","service":"web-api","message":"User login successful","user_id":"12345"}
{"timestamp":"2024-01-15T10:30:05Z","level":"error","service":"web-api","message":"Database connection failed","error":"timeout after 30s"}
{"timestamp":"2024-01-15T10:30:10Z","level":"warn","service":"auth","message":"Rate limit exceeded","ip":"192.168.1.100"}
{"timestamp":"2024-01-15T10:30:15Z","level":"info","service":"web-api","message":"User logout","user_id":"12345"}
{"timestamp":"2024-01-15T10:30:20Z","level":"error","service":"database","message":"Query execution failed","query":"SELECT * FROM users","error":"connection refused"}
EOF

Plain Text Logs

# Create a sample plain text log file
cat > sample.log << EOF
2024-01-15 10:30:00 [INFO] web-api: User login successful (user_id: 12345)
2024-01-15 10:30:05 [ERROR] web-api: Database connection failed - timeout after 30s
2024-01-15 10:30:10 [WARN] auth: Rate limit exceeded from 192.168.1.100
2024-01-15 10:30:15 [INFO] web-api: User logout (user_id: 12345)
2024-01-15 10:30:20 [ERROR] database: Query execution failed - connection refused
EOF

Logfmt Format

# Create a sample logfmt log file
cat > sample.log << EOF
time=2024-01-15T10:30:00Z level=info service=web-api msg="User login successful" user_id=12345
time=2024-01-15T10:30:05Z level=error service=web-api msg="Database connection failed" error="timeout after 30s"
time=2024-01-15T10:30:10Z level=warn service=auth msg="Rate limit exceeded" ip=192.168.1.100
time=2024-01-15T10:30:15Z level=info service=web-api msg="User logout" user_id=12345
time=2024-01-15T10:30:20Z level=error service=database msg="Query execution failed" error="connection refused"
EOF

Gonzo now supports native Kubernetes integration and can connect directly to your cluster using your kubeconfig using "gonzo --k8s-enabled=true". See here for more.

Step 2: Launch Gonzo

Now let's analyze these logs with Gonzo:

# Analyze the log file
gonzo -f sample.log

🎉 Gonzo will launch with a beautiful terminal interface!

Understanding the Interface

When Gonzo opens, you'll see a 5-panel layout inspired by k9s:

Panel Overview

Panel	Description	What You'll See
Word Frequency (top-left)	Most common words	Keywords ranked by frequency
Top Attributes (top-right)	Metadata auto-detected in structured logs	Attributes detected in log message, e.g. in OTel format, or JSON format detected logs
Top Detected Patterns (middle-left)	Log patterns by frequency/volume	Top patterns in log message/body (using Drain3 algorithm)
Log Counts by Severity Over Time (middle-right)	Logs counts over time	Severity distribution, patterns, time series
Log Viewer (bottom)	Live feed of log entries	Colored by severity (red=error, yellow=warn, etc.)

Basic Navigation

Let's explore the interface:

Essential Keyboard Shortcuts

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

Try These Actions

1. Navigate panels: Press Tab to move between the five panels

2. Examine logs: Use arrow keys in the Log Viewer to browse entries

3. View details: Press Enter on a log entry to see full details

4. Explore analytics: Press Enter on the Counts panel for deep analysis

Filtering Your Logs

One of Gonzo's most powerful features is real-time filtering (regex supported):

Basic Filtering

# Press '/' to enter filter mode, then type:
error           # Show only entries containing "error"
error|Error     # Show only entries containing "error" or "Error"

Severity Filtering

Gonzo automatically detects and color-codes log levels:

• 🔴 ERROR - Critical issues requiring attention

• 🟡 WARN - Warnings and potential problems

• 🔵 INFO - Informational messages

• ⚪ DEBUG - Detailed debugging information

Real-Time Log Following

For live log analysis, use the --follow flag:

# Follow a log file as it grows (like tail -f)
gonzo -f /var/log/app.log --follow

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

# Pipe from other commands
kubectl logs -f deployment/my-app | gonzo

Pro Tip: Use Space to pause the live feed when you need to examine something closely. The logs keep buffering in the background!

Next Steps

Now that you've got the basics down, explore these features:

🔍 Advanced Analysis

• Press Enter on the Log Counts panel to see:

  • Time-series heatmaps

  • Top services by severity

  • Service distribution charts

  • 60-minute rolling window analysis

🤖 AI-Powered Insights

Set up AI analysis (hosted or local models supported) for intelligent log insights:

# Set up OpenAI (or your preferred AI provider)
export OPENAI_API_KEY="sk-your-key-here"

# Analyze logs with AI
gonzo -f sample.log --ai-model="gpt-4"

# Press 'i' in log detail view for AI analysis

📊 Multiple Data Sources

Gonzo handles various input methods:

# Multiple files
gonzo -f app.log -f error.log -f debug.log

# Glob patterns  
gonzo -f "/var/log/app/*.log"

# OTLP receiver mode
gonzo --otlp-enabled

# Follow logs in real time (like tail -f)
gonzo -f local.log --follow | gonzo

Common Use Cases

Here are some real-world scenarios to try:

Application Debugging

# Monitor application logs with AI analysis
export OPENAI_API_KEY="your-key"
gonzo -f /var/log/myapp.log --follow --ai-model="gpt-4"

# Filter for errors and get AI insights
# Press '/' then type: error
# Press 'i' in detail view for AI analysis

Kubernetes Monitoring

# Monitor pod logs
kubectl logs -f deployment/frontend | gonzo

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

# With stern (if installed)
stern backend | gonzo

System Administration

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

# Multiple system log files
gonzo -f "/var/log/*.log" --follow

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

Troubleshooting

Gonzo not starting?

• Check that your terminal supports UTF-8

• Verify log file permissions

• Try with a simple test: echo "test" | gonzo

Colors not showing?

• Ensure your terminal supports ANSI colors

• Check if NO_COLOR environment variable is set

Performance issues?

• Adjust buffer sizes: gonzo -f large.log --log-buffer=5000

• Use filtering to reduce data volume

What's Next?

Ready to dive deeper? Check out these guides:

• Interface Overview - Detailed explanation of all panels and features

• Log Input Methods - Files, stdin, OTLP, and more

• AI Integration - Set up intelligent log analysis

• Configuration - Customize Gonzo for your workflow

Need Help?

• ❓ Check Troubleshooting

• 🐛 Report issues on GitHub

• 💬 Join discussions on GitHub Discussions

Learn More

Check out these practical guides:

• A Tale of Two Log Types: Gonzo in Action - Understanding log formats

• AI and a TUI: Practical Logging Tools for SREs - Real-world SRE workflows

---

Congratulations! 🎉 You've completed the Gonzo quick start. You now know how to analyze logs, navigate the interface, and use basic filtering. Time to explore your real log data!