> 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/basic-usage.md).
# Basic Usage
Master the essential Gonzo usage patterns. This guide covers the most common ways to analyze logs and the fundamental workflows you'll use daily.
{% hint style="info" %}
**New to Gonzo?** Complete the Quick Start Tutorial first for a hands-on introduction to the interface.
{% endhint %}
### Core Usage Patterns
#### Reading from Files
The most common way to use Gonzo is analyzing log files directly:
```bash
# Analyze a single log file
gonzo -f application.log
# Analyze multiple specific files
gonzo -f application.log -f error.log -f debug.log
# Use glob patterns for multiple files
gonzo -f "/var/log/*.log"
gonzo -f "/var/log/app/*.log" -f "/var/log/nginx/*.log"
```
{% tabs %}
{% tab title="Single File" %}
Perfect for focused analysis of one application or service:
```bash
gonzo -f /var/log/myapp.log
```
**Best for:**
* Debugging specific applications
* Analyzing archived log files
* Initial investigation of issues
{% endtab %}
{% tab title="Multiple Files" %}
Combine logs from related services for comprehensive analysis:
```bash
gonzo -f api.log -f database.log -f cache.log
```
**Best for:**
* Multi-service debugging
* Correlating events across systems
* Full-stack troubleshooting
{% endtab %}
{% tab title="Glob Patterns" %}
Automatically include all matching files:
```bash
gonzo -f "/var/log/myapp-*.log"
gonzo -f "/logs/**/*.log"
```
**Best for:**
* Rotated log files (app.log, app.log.1, etc.)
* Directory-based log organization
* Dynamic file discovery
{% endtab %}
{% endtabs %}
#### Real-Time Log Following
Monitor logs as they grow, similar to `tail -f`:
```bash
# Follow a single file
gonzo -f /var/log/app.log --follow
# Follow multiple files
gonzo -f "/var/log/*.log" --follow
# Follow with glob patterns
gonzo -f "/var/log/app-*.log" --follow
```
{% hint style="success" %}
**Pro Tip:** Use `Space` to pause the live feed while keeping the data flowing in the background. Press `Space` again to resume auto-scrolling.
{% endhint %}
#### Stdin Processing (Piping)
Gonzo excels at processing log streams from other commands:
{% tabs %}
{% tab title="Basic Piping" %}
```bash
# Analyze existing logs
cat application.log | gonzo
# Process compressed logs
zcat app.log.gz | gonzo
gunzip -c logs.gz | gonzo
```
{% endtab %}
{% tab title="Live Streaming" %}
```bash
# Stream system logs
tail -f /var/log/syslog | gonzo
# Follow multiple files
tail -f /var/log/*.log | gonzo
# Use multitail for complex scenarios
multitail -f /var/log/app.log /var/log/error.log | gonzo
```
{% endtab %}
{% tab title="Container Logs" %}
```bash
# Docker container logs
docker logs -f my-container 2>&1 | gonzo
# Multiple containers
docker logs -f container1 container2 2>&1 | gonzo
# Docker Compose services
docker-compose logs -f | gonzo
```
{% endtab %}
{% tab title="Kubernetes Logs" %}
```bash
# Pod logs
kubectl logs -f deployment/my-app | gonzo
# Multiple pods
kubectl logs -f -l app=backend | gonzo
# With stern (if installed) - get logs from all pods, all namespaces
stern . --all-namespaces --output json | gonzo
```
{% endtab %}
{% endtabs %}
### Command-Line Options
#### Essential Flags
| Flag | Description | Example |
| ----------------------- | ----------------------------- | ------------------------------------- |
| `-h, --help` | Gonzo help | `-h, --help` |
| `-f, --file` | Specify log files or patterns | `gonzo -f app.log` |
| `--follow` | Follow files like `tail -f` | `gonzo -f app.log --follow` |
| `-u, --update-interval` | Dashboard refresh rate | `gonzo -f app.log -u 2s` |
| `-b, --log-buffer` | Maximum log entries to keep | `gonzo -f app.log -b 5000` |
| `--ai-model` | AI model for analysis | `gonzo -f app.log --ai-model="gpt-4"` |
#### Buffer and Performance Tuning
Optimize Gonzo for your log volume and system resources:
```bash
# Large log files - increase buffer
gonzo -f huge.log --log-buffer=10000
# High-frequency logs - slower updates
gonzo -f busy.log --update-interval=5s
# Memory-constrained systems
gonzo -f app.log --memory-size=5000 --log-buffer=1000
# Performance monitoring
gonzo -f app.log --update-interval=500ms --log-buffer=2000
```
### Working with Different Log Formats
Gonzo automatically detects and handles multiple log formats, including [Custom Formats](/controltheory-documentation/gonzo-docs/advanced-features/custom-formats.md). Use the [Quick Start section](/controltheory-documentation/gonzo-docs/getting-started/quick-start.md#step-1-create-sample-logs) to try out a few of the supported log formats.
#### JSON Logs
```json
{"timestamp":"2024-01-15T10:30:00Z","level":"error","service":"api","message":"Database timeout"}
```
**Features:**
* ✅ Automatic field extraction
* ✅ Structured attribute display
* ✅ Nested object support
* ✅ Array handling
#### Logfmt Format
```
time=2024-01-15T10:30:00Z level=error service=api msg="Database timeout" duration=30.5s
```
**Features:**
* ✅ Key-value pair extraction
* ✅ Quoted value support
* ✅ Numeric type detection
* ✅ Space and special character handling
#### Plain Text Logs
```
2024-01-15 10:30:00 [ERROR] api: Database timeout after 30.5 seconds
```
**Features:**
* ✅ Pattern-based level detection
* ✅ Timestamp recognition
* ✅ Service name extraction
* ✅ Word frequency analysis
{% hint style="info" %}
**Format Detection:** Gonzo automatically detects the format of each log entry. You can mix different formats in the same analysis session.
{% endhint %}
### Essential Workflows
#### Debugging Application Issues
```bash
# 1. Start with error-level filtering
gonzo -f app.log --follow
# Press '/' and type: error|Error
# 2. Examine patterns in Counts panel
# Press Enter on Counts panel for detailed analysis
# 3. Use AI for insights (if configured)
# Press 'i' in any log detail view
```
#### Performance Monitoring
```bash
# Monitor multiple services
gonzo -f "/var/log/app-*.log" --follow
# Focus on warnings and errors
# Use filtering press '/': warn|error
# Track response times and patterns
# Watch Word Frequency panel for performance keywords
```
#### System Health Monitoring
```bash
# Monitor system logs
sudo gonzo -f "/var/log/syslog" --follow
# Multi-service monitoring
gonzo -f "/var/log/*.log" --follow
# Filter for critical events
# Use regex in filter press '/': fail|error|critical|timeout
```
### Navigation Essentials
#### Panel Navigation
#### Key Shortcuts for Daily Use
| 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 |
### Configuration for Daily Use
#### Environment Variables
Set these for consistent behavior:
```bash
# Add to your ~/.bashrc or ~/.zshrc
export GONZO_UPDATE_INTERVAL="2s"
export GONZO_LOG_BUFFER="2000"
export GONZO_MEMORY_SIZE="15000"
# AI configuration
export OPENAI_API_KEY="your-key-here"
```
#### Config File Setup
Create `~/.config/gonzo/config.yml` for persistent settings:
```yaml
# Default file patterns
files:
- "/var/log/app.log"
- "/var/log/error.log"
# Enable real-time following
follow: true
# Performance settings
update-interval: 2s
log-buffer: 2000
memory-size: 15000
# AI model preference
ai-model: "gpt-4"
```
### Common Patterns by Use Case
#### Web Application Monitoring
```bash
# Monitor web server and application logs
gonzo -f /var/log/nginx/access.log -f /var/log/app/error.log --follow
# Filter for HTTP errors
# Regex: (4[0-9]{2}|5[0-9]{2}|error)
```
#### Microservices Debugging
```bash
# Monitor all service logs
gonzo -f "/var/log/service-*.log" --follow
# Focus on service communication
# Filter: (http|api|request|response)
```
#### Database Troubleshooting
```bash
# Monitor database logs
gonzo -f /var/log/postgresql/postgresql.log --follow
# Look for performance issues
# Filter: (slow|timeout|deadlock|error)
```
#### CI/CD Pipeline Analysis
```bash
# Analyze build logs
gonzo -f build.log
# Monitor deployment logs
kubectl logs -f deployment/app | gonzo
# Filter for failures
# Regex: (fail|error|exit)
```
### Best Practices
#### 🎯 **Efficient Filtering**
* Start broad, then narrow down with specific filters
* Use regex for pattern matching: `*(api|web)`
* Combine severity with keywords: `*error.*database`
#### ⚡ **Performance Optimization**
* Use `--follow` only when needed for real-time analysis
* Adjust buffer sizes based on log volume
* Filter early to reduce processing overhead
#### 🔍 **Effective Analysis**
* Use the Counts panel for pattern recognition
* Leverage AI analysis for complex issues
* Pause the feed when examining specific entries
#### 🛠️ **Workflow Integration**
* Create shell aliases for common commands
* Use config files for consistent settings
* Combine with other tools (`stern`, `kubectl`, `docker`)
### Troubleshooting Common Issues
#### File Access Problems
```bash
# Permission denied
sudo gonzo -f /var/log/secure.log
# File not found
gonzo -f "/var/log/app*.log" # Use quotes with wildcards
```
#### Performance Issues
```bash
# Large files - increase buffer and slow updates
gonzo -f huge.log --log-buffer=10000 --update-interval=5s
# High-frequency logs - reduce memory usage
gonzo -f busy.log --memory-size=5000
```
#### Display Issues
```bash
# Terminal too small
# Resize terminal or use minimal view
# Colors not showing
unset NO_COLOR
export TERM=xterm-256color
```
### What's Next?
Now that you've mastered basic usage, explore these advanced features:
* **Interface Overview** - Deep dive into each panel
* **Log Input Methods** - OTLP, streaming, and advanced sources
* **Filtering & Search** - Advanced filtering techniques
* **Configuration** - Customize for your workflow
***
**You're now ready to use Gonzo effectively for daily log analysis!** 🚀 These patterns will handle 90% of your log analysis needs.
---
# 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/basic-usage.md?ask=&goal=
```
`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.