# 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](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/advanced-features/custom-log-formats). Use the [Quick Start section](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/quick-start#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.