# User Guide

Master Gonzo's features and workflows with these comprehensive guides. Whether you're analyzing application logs, debugging system issues, or monitoring services in real-time, this section covers everything you need to become proficient with Gonzo.

### What You'll Learn

The User Guide is organized to take you from understanding the interface to mastering advanced analysis techniques:

#### 🖥️ **Understanding the Interface**

Learn how Gonzo's k9s-inspired 2x2 grid layout provides four specialized views of your log data, each optimized for different aspects of analysis.

#### 🎮 **Mastering Navigation**

Discover keyboard shortcuts, mouse controls, and navigation techniques that make log analysis fast and efficient.

#### 📊 **Input Methods & Sources**

Explore all the ways to get log data into Gonzo - from simple files to real-time streams, OpenTelemetry integration, and advanced piping scenarios.

#### 🔍 **Search & Filtering**

Master advanced filtering techniques, regex patterns, and search strategies to quickly find what matters in your logs.

#### 🚀 **Advanced Workflows**

Put it all together with real-world usage patterns, performance optimization, and power-user techniques.

### Guide Overview

{% hint style="info" %}
**New to Gonzo?** Start with Interface Overview to understand the core layout, then work through the guides in order.
{% endhint %}

#### Interface Overview

**Essential foundation for all Gonzo usage**

Understand the 2x2 grid layout and what each panel does:

* **Log Viewer** - Real-time log feed with color-coded severity levels
* **Word Frequency** - Most common terms and keywords in your logs
* **Attributes** - Structured data extracted from JSON and logfmt logs
* **Counts** - Analytics hub with patterns, trends, and time-series data

**Time to complete:** 10-15 minutes\
**Prerequisites:** Basic Gonzo installation

***

#### Navigation & Controls

**Master efficient log analysis workflows**

Complete reference for keyboard shortcuts and mouse controls:

* Panel switching and focus management
* Scrolling and selection techniques
* Global controls (pause, reset, filtering)
* Context-sensitive shortcuts for each panel

**Time to complete:** 15-20 minutes\
**Prerequisites:** Interface Overview

***

#### Log Input Methods

**Get data into Gonzo from any source**

Comprehensive coverage of all input methods:

* File analysis (single, multiple, glob patterns)
* Real-time log following (`--follow` mode)
* Stdin processing and piping workflows
* OpenTelemetry Protocol (OTLP) integration
* Advanced streaming scenarios

**Time to complete:** 20-25 minutes\
**Prerequisites:** Basic command-line familiarity

***

#### Filtering & Search

**Find exactly what you need in your logs**

Advanced techniques for log filtering and search:

* Regex patterns and examples
* Attribute-based filtering
* Severity-level filtering
* Text highlighting and search
* Performance optimization for large datasets

**Time to complete:** 20-30 minutes\
**Prerequisites:** Interface Overview, basic regex knowledge helpful

***

#### Detailed Usage Guide

**Real-world patterns and advanced techniques**

Comprehensive usage patterns and power-user techniques:

* Complex multi-source analysis
* Performance tuning and optimization
* Integration with existing toolchains
* Troubleshooting common scenarios
* Best practices from the community

**Time to complete:** 30-45 minutes\
**Prerequisites:** All previous User Guide sections

### Learning Paths

Choose your path based on your current experience and goals:

{% tabs %}
{% tab title="New User Path" %}
**Complete beginner to Gonzo**

1. Interface Overview - Understand the layout
2. Navigation & Controls - Learn basic shortcuts
3. Log Input Methods - Start with file analysis
4. Filtering & Search - Find relevant logs
5. Practice with your own log files

**Estimated time:** 2-3 hours total
{% endtab %}

{% tab title="Experienced User Path" %}
**Familiar with log analysis tools**

1. Interface Overview - See what's unique about Gonzo
2. Log Input Methods - Advanced integration patterns
3. Filtering & Search - Regex and advanced techniques
4. Detailed Usage Guide - Power-user workflows

**Estimated time:** 1-2 hours total
{% endtab %}

{% tab title="Integration Focused" %}
**Need to integrate Gonzo into existing workflows**

1. Log Input Methods - OTLP and streaming integration
2. Interface Overview - Understand output and analysis
3. Detailed Usage Guide - Advanced patterns
4. Check Integration Examples section

**Estimated time:** 1-2 hours total
{% endtab %}
{% endtabs %}

### Quick Reference

Once you're familiar with the basics, these quick references will be handy:

#### Most-Used Keyboard Shortcuts

| Key                 | Action            | Context       |
| ------------------- | ----------------- | ------------- |
| `Tab` / `Shift+Tab` | Switch panels     | Global        |
| `Space`             | Pause/unpause     | Global        |
| `/`                 | Enter filter mode | Global        |
| `↑/↓` or `k/j`      | Navigate          | Any list      |
| `Enter`             | View details      | Selected item |
| `r`                 | Reset data        | Global        |
| `q`                 | Quit              | Global        |

#### Essential Command Patterns

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

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

# Multiple sources
gonzo -f "*.log" --follow

# Piping from other tools
kubectl logs -f deployment/app | gonzo
```

### What's Next?

After completing the User Guide, you'll be ready for:

* **Advanced Features** - AI integration, pattern analysis, and complex workflows
* **Configuration** - Customize Gonzo for your specific needs
* **Integration Examples** - Real-world scenarios and use cases
* **Troubleshooting** - Solutions to common problems

### Getting Help

If you get stuck while working through these guides:

* 📖 Check the specific guide's troubleshooting sections
* 🔍 Use the search function to find related topics
* 🐛 Report documentation issues on [GitHub](https://github.com/control-theory/gonzo/issues)
* 💬 Ask questions in [GitHub Discussions](https://github.com/control-theory/gonzo/discussions)

***

**Ready to become a Gonzo power user?** 🚀 Start with the Interface Overview and work your way through each guide!


---

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

```
GET https://docs.controltheory.com/backup/user-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.