> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/getting-started/quick-start.md).

# 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 ](/controltheory-documentation/gonzo-docs/integration-examples/container-environments/kubernetes.md)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="/files/CXr7uk4yyMk8Y3vMfs98" 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](/controltheory-documentation/gonzo-docs/troubleshooting.md)
* 🐛 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!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/getting-started/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.