# Quick Start

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

{% hint style="info" %}
**Prerequisites:** Make sure you have Gonzo installed. If not, check the Installation Guide first.
{% endhint %}

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

{% tabs %}
{% tab title="JSON Logs" %}

```bash
# 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
```

{% endtab %}

{% tab title="Plain Text Logs" %}

```bash
# 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
```

{% endtab %}

{% tab title="Logfmt Format" %}

```bash
# 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
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}

#### Gonzo now supports native Kubernetes integration and can connect directly to your cluster using your kubeconfig using "gonzo --k8s-enabled=true".  See [here ](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/container-environments/kubernetes)for more.

{% endhint %}

#### Step 2: Launch Gonzo

Now let's analyze these logs with Gonzo:

```bash
# 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

<figure><img src="https://3483934249-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SdDsOcMkqsJoxnydVXB%2Fuploads%2F5FAmDBt9sU4MRrQl9c9a%2FMain%20Gonzo%20Window%20Guide.png?alt=media&#x26;token=381914b6-868a-41b9-9c76-9f8322682301" alt=""><figcaption></figcaption></figure>

| 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

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

```bash
# 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
```

{% hint style="success" %}
**Pro Tip:** Use `Space` to pause the live feed when you need to examine something closely. The logs keep buffering in the background!
{% endhint %}

### 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](#ai-powered-insights) (hosted or local models supported) for intelligent log insights:

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

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

{% tabs %}
{% tab title="Application Debugging" %}

```bash
# 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
```

{% endtab %}

{% tab title="Kubernetes Monitoring" %}

```bash
# 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
```

{% endtab %}

{% tab title="System Administration" %}

```bash
# 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
```

{% endtab %}
{% endtabs %}

### 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](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/troubleshooting)
* 🐛 Report issues on [GitHub](https://github.com/control-theory/gonzo/issues)
* 💬 Join discussions on [GitHub Discussions](https://github.com/control-theory/gonzo/discussions)

### Learn More

Check out these practical guides:

* [A Tale of Two Log Types: Gonzo in Action](https://www.controltheory.com/blog/a-tale-of-two-log-types-gonzo-in-action/) - Understanding log formats
* [AI and a TUI: Practical Logging Tools for SREs](https://www.controltheory.com/blog/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!