# 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](https://k9scli.io/), 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

{% hint style="success" %}
**Perfect for:** Application debugging, system monitoring, microservice analysis, and any scenario where you need to quickly understand what's happening in your logs.
{% endhint %}

### 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:

{% tabs %}
{% tab title="After Installation" %}
✅ **You can run Gonzo**

```bash
gonzo --version
```

✅ **Shell completion works** (optional but recommended)

```bash
gonzo <tab><tab>  # Shows available commands
```

✅ **Ready for your first analysis**
{% endtab %}

{% tab title="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)
{% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

### 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:

```bash
# Basic file analysis
gonzo -f application.log

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

# Gonzo Native K8s Support (leverage your kubeconfig)
gonzo --k8s-enabled=true

# 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:

{% tabs %}
{% tab title="Application Debugging" %}
**Scenario:** Your web application is throwing errors

```bash
# 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)
  {% endtab %}

{% tab title="System Monitoring" %}
**Scenario:** System performance seems slow

```bash
# 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
  {% endtab %}

{% tab title="Container Troubleshooting" %}
**Scenario:** Docker container keeps crashing

```bash
# 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
  {% endtab %}
  {% endtabs %}

### 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**](https://github.com/control-theory/gonzo/discussions) - Ask questions and share tips
* [**GitHub Issues**](https://github.com/control-theory/gonzo/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!