### License
Gonzo is licensed under the MIT License. See [LICENSE](https://github.com/control-theory/gonzo/blob/main/LICENSE) for details.
### Credits
#### Core Team
* [ControlTheory](https://github.com/control-theory) - Development and maintenance
#### Contributors
Thanks to all contributors! See [Contributors](https://github.com/control-theory/gonzo/graphs/contributors) for complete list.
#### Special Thanks
* [Charm](https://charm.sh/) - Bubble Tea, Lipgloss, Bubbles
* [OpenTelemetry](https://opentelemetry.io/) - OTLP specification
* [k9s](https://k9scli.io/) - TUI inspiration
* Community contributors and users
### Archive
For historical versions before 0.1.0, see the [Git history](https://github.com/control-theory/gonzo/commits/main).
***
### Changelog Format
This changelog follows these conventions:
* **Added**: New features
* **Changed**: Changes to existing functionality
* **Deprecated**: Soon-to-be removed features
* **Removed**: Removed features
* **Fixed**: Bug fixes
* **Security**: Security fixes
**Version Format**: `MAJOR.MINOR.PATCH`
* **MAJOR**: Breaking changes
* **MINOR**: New features (backward compatible)
* **PATCH**: Bug fixes (backward compatible)
***
{% hint style="info" %}
**Stay Updated**: Watch the [GitHub repository](https://github.com/control-theory/gonzo) to be notified of new releases.
{% endhint %}
{% hint style="success" %}
**Latest Version**: Check [Releases](https://github.com/control-theory/gonzo/releases) for the most recent version and download links.
{% endhint %}
# Input Methods Overflow
Gonzo offers multiple powerful ways to feed log data into its analysis engine. From simple file analysis to real-time OpenTelemetry streams, this guide covers all input methods and their optimal use cases.
### Input Method Overview
Gonzo supports four primary input methods, each optimized for different scenarios:
| Method | Best For | Command Example | Real-time? |
| --------------------- | ------------------------------ | ------------------------------ | ---------- |
| **📁 File Input** | Static log analysis, debugging | `gonzo -f app.log` | No |
| **📈 File Following** | Real-time monitoring | `gonzo -f app.log --follow` | Yes |
| **🔄 Stdin Piping** | Integration with tools | `kubectl logs -f pod \| gonzo` | Yes |
| **🌐 OTLP Receiver** | OpenTelemetry integration | `gonzo --otlp-enabled` | Yes |
### File Input Methods
#### Single File Analysis
Perfect for debugging specific issues or analyzing archived logs:
```bash
# Basic file analysis
gonzo -f application.log
# Absolute paths
gonzo -f /var/log/nginx/access.log
# Relative paths
gonzo -f logs/app.log
# Compressed files (via piping)
zcat app.log.gz | gonzo
gunzip -c error.log.gz | gonzo
```
**Best Practices:**
* Start with single files to understand the data structure
* Use absolute paths to avoid "file not found" errors
* Check file permissions if Gonzo can't access the file
#### Multiple File Analysis
Combine logs from related services for comprehensive analysis:
```bash
# Multiple specific files
gonzo -f api.log -f database.log -f cache.log
# Mix different log types
gonzo -f application.log -f /var/log/syslog -f error.log
# Different directories
gonzo -f /var/log/app.log -f /home/user/debug.log
```
{% tabs %}
{% tab title="Related Services" %}
**Microservices Architecture:**
```bash
# Analyze all service logs together
gonzo -f api-gateway.log -f user-service.log -f payment-service.log
# Include infrastructure logs
gonzo -f app.log -f nginx.log -f postgres.log
```
**Benefits:**
* Correlate events across services
* See timing relationships
* Identify cascade failures
{% endtab %}
{% tab title="Different Severities" %}
**Separate Log Levels:**
```bash
# Combine different severity files
gonzo -f application.log -f error.log -f debug.log
# Include system and application logs
gonzo -f app.log -f /var/log/syslog
```
**Benefits:**
* Complete picture of system state
* Context around error events
* Debug information correlation
{% endtab %}
{% endtabs %}
#### Glob Pattern Input
Automatically include multiple files using pattern matching:
```bash
# All .log files in current directory
gonzo -f "*.log"
# All log files in a directory
gonzo -f "/var/log/*.log"
# Specific patterns
gonzo -f "/var/log/app-*.log"
gonzo -f "/logs/**/*.log"
# Multiple patterns
gonzo -f "/var/log/app*.log" -f "/var/log/nginx*.log"
```
**Glob Pattern Examples:**
| Pattern | Matches | Use Case |
| ---------------------- | --------------------------------------- | ------------------------- |
| `"*.log"` | All .log files in current dir | Development debugging |
| `"/var/log/*.log"` | All .log files in /var/log | System administration |
| `"app-*.log"` | app-2024.log, app-error.log | Application-specific logs |
| `"/logs/**/*.log"` | All .log files recursively | Complex log hierarchies |
| `"*-{error,warn}.log"` | Files ending in -error.log or -warn.log | Specific severity levels |
{% hint style="warning" %}
**Important:** Always quote glob patterns to prevent shell expansion. Use `"*.log"` not `*.log`.
{% endhint %}
**Advanced Glob Techniques:**
```bash
# Rotated log files
gonzo -f "/var/log/app.log*" # app.log, app.log.1, app.log.2, etc.
# Date-based logs
gonzo -f "/logs/app-2024-*.log" # app-2024-01-15.log, etc.
# Multiple services with patterns
gonzo -f "/var/log/{nginx,apache}/*.log"
# Exclude certain files (use find + piping)
find /var/log -name "*.log" ! -name "*debug*" -exec gonzo -f {} +
```
### Real-Time File Following
Monitor logs as they grow, similar to `tail -f`:
#### Basic Following
```bash
# Follow a single file
gonzo -f /var/log/app.log --follow
# Follow multiple files
gonzo -f app.log -f error.log --follow
# Follow with glob patterns
gonzo -f "/var/log/*.log" --follow
```
**How Following Works:**
* Gonzo monitors files for changes using inotify (Linux) or similar mechanisms
* New log entries appear automatically in the interface
* Handles log rotation gracefully
* Efficiently processes only new content
#### Advanced Following Scenarios
{% tabs %}
{% tab title="Application Monitoring" %}
**Development Environment:**
```bash
# Follow application logs during development
gonzo -f logs/app.log --follow
# Include error logs
gonzo -f logs/app.log -f logs/error.log --follow
# With configuration
gonzo -f logs/*.log --follow --log-buffer=5000
```
**Production Monitoring:**
```bash
# Monitor production logs
gonzo -f /var/log/myapp/*.log --follow
# Include system logs
gonzo -f /var/log/myapp.log -f /var/log/syslog --follow
```
{% endtab %}
{% tab title="System Administration" %}
**Security Monitoring:**
```bash
# Monitor security logs
sudo gonzo -f /var/log/auth.log --follow
# Multiple security sources
sudo gonzo -f "/var/log/{auth,secure,audit}*.log" --follow
```
**Performance Monitoring:**
```bash
# Monitor performance-related logs
gonzo -f /var/log/nginx/access.log -f /var/log/app/perf.log --follow
# System resource logs
gonzo -f /var/log/syslog -f /var/log/kern.log --follow
```
{% endtab %}
{% endtabs %}
#### Following Best Practices
**Performance Optimization:**
```bash
# Large files - adjust buffer size
gonzo -f huge.log --follow --log-buffer=10000
# High-frequency logs - slower updates
gonzo -f busy.log --follow --update-interval=5s
# Memory-constrained systems
gonzo -f app.log --follow --memory-size=5000
```
**Monitoring Multiple Sources:**
```bash
# Start with most important logs
gonzo -f app.log --follow
# Add more sources gradually
gonzo -f app.log -f error.log --follow
# Full monitoring setup
gonzo -f "/var/log/app/*.log" --follow --log-buffer=5000 --update-interval=2s
```
### Stdin Processing (Piping)
Integrate Gonzo with existing tools and command pipelines:
#### Basic Piping
```bash
# Basic piping from other commands
cat application.log | gonzo
# Process compressed logs
zcat app.log.gz | gonzo
gunzip -c logs.gz | gonzo
# Stream from remote systems
ssh server "cat /var/log/app.log" | gonzo
```
#### Real-Time Streaming
**Traditional Unix Tools:**
```bash
# Stream with tail
tail -f /var/log/app.log | gonzo
# Multiple files with tail
tail -f /var/log/*.log | gonzo
# Advanced tailing with multitail
multitail -f /var/log/app.log /var/log/error.log | gonzo
```
**System Monitoring:**
```bash
# System logs
sudo tail -f /var/log/syslog | gonzo
# Journal logs (systemd)
journalctl -f | gonzo
# Specific service logs
journalctl -f -u nginx | gonzo
```
#### Container Integration
{% tabs %}
{% tab title="Docker" %}
**Single Container:**
```bash
# Current container logs
docker logs my-container | gonzo
# Follow container logs
docker logs -f my-container 2>&1 | gonzo
# Multiple containers
docker logs -f container1 container2 2>&1 | gonzo
```
**Docker Compose:**
```bash
# All services
docker-compose logs -f | gonzo
# Specific services
docker-compose logs -f web api database | gonzo
# With timestamps
docker-compose logs -f -t | gonzo
```
{% endtab %}
{% tab title="Kubernetes" %}
**Pod Logs:**
```bash
# Single pod
kubectl logs -f pod/my-app | gonzo
# Deployment logs
kubectl logs -f deployment/my-app | gonzo
# Multiple pods
kubectl logs -f -l app=backend | gonzo
```
**Advanced Kubernetes:**
```bash
# Previous container instance
kubectl logs -f pod/my-app --previous | gonzo
# Specific container in pod
kubectl logs -f pod/my-app -c sidecar | gonzo
# All containers in pod
kubectl logs -f pod/my-app --all-containers | gonzo
```
**With Stern (if installed):**
```bash
# All pods with label
stern backend | gonzo
# Pods in specific namespace
stern . -n production | gonzo
# With context and coloring
stern api --context=prod --color=always | gonzo
```
{% endtab %}
{% endtabs %}
#### Advanced Piping Scenarios
**Network Sources:**
```bash
# Remote syslog
nc -l 514 | gonzo
# SSH tunneling
ssh -L 8514:logserver:514 server "nc localhost 8514" | gonzo
# HTTP log streaming
curl -s http://logserver/stream | gonzo
```
**Complex Processing:**
# Filter before Gonzo
tail -f /var/log/app.log | grep -v DEBUG | gonzo
# Transform data
tail -f /var/log/app.log | sed 's/old/new/g' | gonzo
# Multiple sources combined
( tail -f app.log & tail -f error.log ) | gonzo
### Input Method Selection Guide
Choose the right input method based on your scenario:
#### Development & Debugging
```bash
# Local development - single application
gonzo -f logs/app.log --follow
# Debugging specific issues
gonzo -f error.log
# Multiple local services
gonzo -f "logs/*.log" --follow
```
#### Production Monitoring
```bash
# Container environments
kubectl logs -f deployment/app | gonzo
# Traditional servers
gonzo -f "/var/log/app/*.log" --follow
# OpenTelemetry-enabled applications
gonzo --otlp-enabled
```
#### System Administration
```bash
# System health monitoring
sudo gonzo -f "/var/log/{syslog,auth.log,kern.log}" --follow
# Security analysis
sudo tail -f /var/log/auth.log | gonzo
# Performance investigation
gonzo -f "/var/log/nginx/*.log"
```
#### Integration Scenarios
```bash
# CI/CD pipelines
build-logs | gonzo
# Monitoring alerts
alert-stream | gonzo
# Log aggregation
rsyslog-stream | gonzo
```
### Performance Considerations
#### Buffer Sizing
Optimize for your log volume and available memory:
```bash
# High-volume logs
gonzo -f busy.log --log-buffer=10000 --memory-size=20000
# Memory-constrained systems
gonzo -f app.log --log-buffer=1000 --memory-size=5000
# Balanced configuration
gonzo -f app.log --log-buffer=2000 --memory-size=15000
```
#### Update Intervals
Balance responsiveness with system resources:
```bash
# Real-time responsiveness (default)
gonzo -f app.log --follow --update-interval=1s
# Balanced performance
gonzo -f app.log --follow --update-interval=2s
# Resource conservation
gonzo -f app.log --follow --update-interval=5s
```
#### Input-Specific Optimizations
| Input Method | Optimization | Configuration |
| ------------------ | --------------------------------- | ------------------------------ |
| **File Following** | Use larger buffers | `--log-buffer=5000` |
| **Stdin Piping** | Ensure smooth pipeline | \`command |
| **OTLP** | Tune batch sizes | OpenTelemetry collector config |
| **Multiple Files** | Balance file count vs performance | Combine related files |
### Troubleshooting Input Issues
#### File Access Problems
```bash
# Permission denied
sudo gonzo -f /var/log/secure.log
# File not found with globs
gonzo -f "/path/to/*.log" # Use quotes!
# Check file permissions
ls -la logfile.log
```
#### Following Issues
```bash
# File rotation problems
# Gonzo handles this automatically, but check:
ls -la /var/log/app.log*
# High CPU usage
# Reduce update frequency:
gonzo -f app.log --follow --update-interval=5s
```
#### Piping Problems
```bash
# Broken pipe errors
# Ensure Gonzo can handle the data rate:
slow-producer | gonzo --log-buffer=10000
# Buffer full issues
# Increase buffer size or filter at source:
noisy-source | grep -v DEBUG | gonzo
```
### Advanced Input Patterns
#### Hybrid Approaches
Combine multiple input methods for comprehensive monitoring:
```bash
# OTLP + file backup
gonzo --otlp-enabled -f backup.log --follow
# Real-time + historical analysis
# Terminal 1: gonzo -f app.log --follow
# Terminal 2: gonzo -f historical-logs.log
# Primary + secondary sources
gonzo -f primary.log --follow & kubectl logs -f secondary | gonzo
```
#### Custom Input Scripts
Create wrapper scripts for complex scenarios:
```bash
#!/bin/bash
# monitor-all.sh
exec gonzo \
-f "/var/log/app/*.log" \
-f "/var/log/nginx/*.log" \
--follow \
--log-buffer=5000 \
--update-interval=2s
```
# AI Setup & Configuration
Get AI-powered log analysis working in minutes. This guide covers everything from basic API key setup to advanced configuration options for all supported AI providers.
{% hint style="success" %}
**Quick Start:** Set `OPENAI_API_KEY` environment variable and run `gonzo -f your-logs.log --ai-model="gpt-4"`. That's it!
{% endhint %}
### Choose Your Setup Path
Select the approach that best fits your needs:
{% tabs %}
{% tab title="Local AI (Ollama)" %}
**Best for: Privacy, unlimited usage, no API costs**
**Requirements:**
* 8GB+ RAM (16GB+ recommended)
* Local compute resources
* Ollama installation
**Setup time:** 10-15 minutes
{% endtab %}
{% tab title="Local AI (LM Studio)" %}
**Best for: Development, testing, easy local setup**
**Requirements:**
* 8GB+ RAM
* LM Studio application
* Downloaded model
**Setup time:** 5-10 minutes
{% endtab %}
{% tab title="OpenAI API" %}
**Best for: Production use, reliability, best AI quality**
**Requirements:**
* OpenAI API account
* Valid API key with credits
* Internet connection
**Setup time:** 2-3 minutes
{% endtab %}
{% tab title="Custom API" %}
**Best for: Enterprise, existing AI infrastructure**
**Requirements:**
* OpenAI-compatible API endpoint
* Authentication credentials
* Network access to API
**Setup time:** 5-15 minutes
{% endtab %}
{% endtabs %}
### OpenAI Setup
#### Step 1: Get Your API Key
1. **Visit** [**OpenAI API Platform**](https://platform.openai.com/)
2. **Create account or sign in**
3. **Navigate to API Keys** ()
4. **Create new secret key**
5. **Copy the key** (starts with `sk-`)
{% hint style="warning" %}
**Important:** Save your API key securely. OpenAI only shows it once, and you'll need it for Gonzo configuration.
{% endhint %}
#### Step 2: Configure Environment
**Method 1: Environment Variable (Recommended)**
```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.profile
export OPENAI_API_KEY="sk-your-actual-api-key-here"
# Reload your shell configuration
source ~/.bashrc # or ~/.zshrc
```
**Method 2: Session Variable**
```bash
# Set for current session only
export OPENAI_API_KEY="sk-your-actual-api-key-here"
# Verify it's set
echo $OPENAI_API_KEY
```
**Method 3: Configuration File**
```bash
# Create Gonzo config file
mkdir -p ~/.config/gonzo
cat > ~/.config/gonzo/config.yml << EOF
# AI Configuration
ai-model: "gpt-4"
# Environment variables can also be set in config
# But API keys are more secure as environment variables
EOF
```
#### Step 3: Test Your Setup
```bash
# Test with automatic model selection
gonzo -f your-logs.log
# Test with specific model
gonzo -f your-logs.log --ai-model="gpt-4"
# Test with cheaper model for development
gonzo -f your-logs.log --ai-model="gpt-3.5-turbo"
```
#### Step 4: Verify AI Features Work
```bash
# 1. Start Gonzo with your logs
gonzo -f application.log --ai-model="gpt-4"
# 2. Navigate to a log entry and press 'i'
# You should see AI analysis of the log entry
# 3. Try the model switcher with 'm'
# You should see available OpenAI models
# 4. Test AI chat with 'c' in log details
# You should be able to have a conversation about the logs
```
### Local AI Setup (Ollama)
#### Step 1: Install Ollama
{% tabs %}
{% tab title="Linux" %}
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Verify installation
ollama --version
```
{% endtab %}
{% tab title="macOS" %}
```bash
# Option 1: Download from website
# Visit https://ollama.ai/download and download macOS installer
# Option 2: Homebrew
brew install ollama
# Verify installation
ollama --version
```
{% endtab %}
{% tab title="Windows" %}
```bash
# Download from https://ollama.ai/download
# Run the installer
# Open PowerShell or Command Prompt
# Verify installation
ollama --version
```
{% endtab %}
{% endtabs %}
#### Step 2: Start Ollama Service
```bash
# Start Ollama server (required for Gonzo to connect)
ollama serve
# This should show:
# Ollama is running on http://localhost:11434
```
{% hint style="info" %}
**Keep this running:** The `ollama serve` command needs to stay running for Gonzo to access AI features. Consider running it in a separate terminal or as a background service.
{% endhint %}
#### Step 3: Download AI Models
```bash
# Download recommended models for log analysis
ollama pull llama3 # Good general-purpose model (4.7GB)
ollama pull mistral # Faster, smaller model (4.1GB)
ollama pull codellama # Good for technical logs (3.8GB)
# Or download a larger, more capable model
ollama pull llama3:70b # Very capable but requires 40GB+ RAM
# List available models
ollama list
```
**Model Recommendations by System:**
| RAM | Recommended Model | Size | Performance |
| ----- | ----------------- | ----- | ------------------------------ |
| 8GB | mistral | 4.1GB | Good for basic analysis |
| 16GB | llama3 | 4.7GB | Excellent for most use cases |
| 32GB+ | llama3:70b | 40GB | Best quality, production-ready |
#### Step 4: Configure Gonzo for Ollama
```bash
# Set environment variables for Ollama
export OPENAI_API_KEY="ollama" # Special key for Ollama
export OPENAI_API_BASE="http://localhost:11434" # Ollama endpoint
# Verify Ollama is accessible
curl http://localhost:11434/api/tags
```
#### Step 5: Test Ollama Integration
```bash
# Test with automatic model selection
gonzo -f your-logs.log
# Test with specific model
gonzo -f your-logs.log --ai-model="llama3"
# Test model switching
# Press 'm' in Gonzo to see available Ollama models
```
### Local LM Studio Setup
#### Step 1: Install LM Studio
1. **Download LM Studio** from
2. **Install the application** for your operating system
3. **Launch LM Studio**
#### Step 2: Download Models
1. **Open LM Studio**
2. **Go to "Discover" tab**
3. **Search and download recommended models:**
* `microsoft/DialoGPT-medium` (lightweight, good for testing)
* `meta-llama/Llama-2-7b-chat-hf` (balanced performance)
* `meta-llama/Llama-2-13b-chat-hf` (better quality, needs more RAM)
#### Step 3: Start Model Server
1. **Go to "Local Server" tab in LM Studio**
2. **Select your downloaded model**
3. **Click "Start Server"**
4. **Note the server URL** (usually `http://localhost:1234`)
#### Step 4: Configure Gonzo for LM Studio
```bash
# Set environment variables for LM Studio
export OPENAI_API_KEY="local-key" # Any non-empty value
export OPENAI_API_BASE="http://localhost:1234/v1" # Note the /v1 suffix
# Test connectivity
curl http://localhost:1234/v1/models
```
#### Step 5: Test LM Studio Integration
```bash
# Test with LM Studio
gonzo -f your-logs.log
# The model will be auto-selected from whatever's running in LM Studio
# Use 'm' to see available models
```
### Custom API Setup
#### Enterprise AI Services
**Azure OpenAI Service:**
```bash
export OPENAI_API_KEY="your-azure-key"
export OPENAI_API_BASE="https://your-resource.openai.azure.com/"
export OPENAI_API_TYPE="azure"
export OPENAI_API_VERSION="2023-05-15"
```
**AWS Bedrock (via compatible proxy):**
```bash
export OPENAI_API_KEY="your-aws-access-key"
export OPENAI_API_BASE="https://your-bedrock-proxy.amazonaws.com/v1"
```
**Custom OpenAI-Compatible API:**
```bash
export OPENAI_API_KEY="your-custom-api-key"
export OPENAI_API_BASE="https://your-ai-service.com/v1"
```
#### Testing Custom APIs
```bash
# Test API connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
"$OPENAI_API_BASE/models"
# Test with Gonzo
gonzo -f test-logs.log --ai-model="your-model-name"
```
### Real-World Examples
See AI features in action:
* [AI and a TUI: Practical Logging Tools for SREs](https://www.controltheory.com/blog/ai-and-a-tui-practical-logging-tools-for-sres/) - Practical AI use cases for incident response
### Advanced Configuration
#### Configuration File Setup
Create a comprehensive configuration file for persistent settings:
```bash
# Create configuration directory
mkdir -p ~/.config/gonzo
# Create comprehensive config file
cat > ~/.config/gonzo/config.yml << EOF
# AI Configuration
ai-model: "gpt-4" # Default model
ai-auto-select: true # Auto-select best available model
# File and performance settings
files:
- "/var/log/app/*.log"
follow: true
update-interval: 2s
log-buffer: 5000
# AI-specific performance settings
ai-context-size: 4000 # Maximum context for AI analysis
ai-response-timeout: 30s # Timeout for AI responses
ai-max-retries: 3 # Retry failed AI requests
# Development vs Production settings
profiles:
development:
ai-model: "gpt-3.5-turbo" # Cheaper model for dev
update-interval: 1s # Faster updates
production:
ai-model: "gpt-4" # Best model for production
update-interval: 5s # Conservative updates
EOF
```
#### Environment-Specific Configurations
**Development Environment:**
```bash
# ~/.config/gonzo/dev-config.yml
ai-model: "gpt-3.5-turbo" # Cost-effective
update-interval: 1s # Responsive
log-buffer: 2000 # Smaller buffer
ai-context-size: 2000 # Reduce token usage
```
**Production Environment:**
```bash
# ~/.config/gonzo/prod-config.yml
ai-model: "gpt-4" # Best quality
update-interval: 5s # Conservative
log-buffer: 10000 # Larger buffer
ai-context-size: 8000 # More context
ai-response-timeout: 60s # Longer timeout
```
**Usage:**
```bash
# Use specific configuration
gonzo --config ~/.config/gonzo/dev-config.yml -f logs/debug.log
gonzo --config ~/.config/gonzo/prod-config.yml -f /var/log/app.log
```
### Multi-Provider Setup
#### Switching Between Providers
**Script for Easy Provider Switching:**
```bash
#!/bin/bash
# ai-provider-switch.sh
switch_to_openai() {
export OPENAI_API_KEY="sk-your-openai-key"
export OPENAI_API_BASE=""
echo "Switched to OpenAI"
}
switch_to_ollama() {
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
echo "Switched to Ollama"
}
switch_to_lmstudio() {
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"
echo "Switched to LM Studio"
}
# Usage: source ai-provider-switch.sh && switch_to_openai
```
#### Provider-Specific Aliases
```bash
# Add to ~/.bashrc or ~/.zshrc
# OpenAI for production incidents
alias gonzo-openai='OPENAI_API_KEY="sk-your-key" \
OPENAI_API_BASE="" \
gonzo --ai-model="gpt-4"'
# Ollama for development
alias gonzo-local='OPENAI_API_KEY="ollama" \
OPENAI_API_BASE="http://localhost:11434" \
gonzo --ai-model="llama3"'
# LM Studio for testing
alias gonzo-lms='OPENAI_API_KEY="local-key" \
OPENAI_API_BASE="http://localhost:1234/v1" \
gonzo'
```
### Troubleshooting Setup Issues
#### OpenAI Issues
**"Invalid API Key" Error:**
```bash
# Check API key is set correctly
echo $OPENAI_API_KEY
# Verify API key format (should start with 'sk-')
# Test API key directly
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
https://api.openai.com/v1/models
```
**"Rate limit exceeded" Error:**
```bash
# Check your OpenAI usage limits
# Visit https://platform.openai.com/account/usage
# Use cheaper model temporarily
gonzo -f logs.log --ai-model="gpt-3.5-turbo"
# Add delays between requests (automatic in Gonzo)
```
**"Insufficient credits" Error:**
```bash
# Add credits to your OpenAI account
# Visit https://platform.openai.com/account/billing
# Check current balance
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
https://api.openai.com/v1/dashboard/billing/subscription
```
#### Ollama Issues
**"Connection refused" Error:**
```bash
# Check if Ollama is running
ps aux | grep ollama
# Start Ollama if not running
ollama serve
# Check if port is accessible
curl http://localhost:11434/api/tags
```
**"Model not found" Error:**
```bash
# List available models
ollama list
# Download missing model
ollama pull llama3
# Verify model is available
ollama show llama3
```
**High Memory Usage:**
```bash
# Use smaller model
ollama pull mistral # 4.1GB instead of 7GB+
# Monitor memory usage
htop
# Restart Ollama if memory issues persist
killall ollama
ollama serve
```
#### LM Studio Issues
**"No models available" Error:**
```bash
# Check LM Studio is running with server started
# Verify model is loaded in LM Studio
# Check server URL is correct (usually :1234)
# Test connectivity
curl http://localhost:1234/v1/models
```
**"Model loading failed" Error:**
```bash
# Check available RAM
free -h
# Try smaller model in LM Studio
# Restart LM Studio application
# Verify model file isn't corrupted
```
#### Network and Firewall Issues
**Corporate Firewall:**
```bash
# Test connectivity to AI providers
curl -I https://api.openai.com
curl -I http://localhost:11434 # For Ollama
curl -I http://localhost:1234 # For LM Studio
# Configure proxy if needed
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
```
**SSL Certificate Issues:**
```bash
# Skip SSL verification (not recommended for production)
export PYTHONHTTPSVERIFY=0
# Or install proper certificates
# Contact your IT department for certificate installation
```
### What's Next?
Now that you have AI configured, explore these guides:
* **AI Providers Guide** - Detailed setup for specific providers
* **Using AI Features** - Master AI-powered workflows and analysis
* **Log Analysis** - Combine AI with algorithmic analysis
Or start using AI features immediately:
```bash
# Start analyzing with AI
gonzo -f your-logs.log --ai-model="gpt-4"
# Try these AI features:
# - Press 'i' on any log entry for analysis
# - Press 'c' in log details for interactive chat
# - Press 'm' to switch between AI models
```
***
**Your AI-powered log analysis is ready!** 🤖 You can now get intelligent insights, natural language explanations, and automated pattern recognition for any log analysis task.
# Old Configuration Cover Page
### Configuration Philosophy
Gonzo follows a layered configuration approach:
1. **Sensible defaults** - Works great out of the box with zero configuration
2. **Environment variables** - Quick overrides for common settings
3. **Command-line flags** - Session-specific adjustments
4. **Configuration files** - Persistent, sophisticated setups
5. **Priority system** - CLI flags override config files, which override environment variables
{% hint style="success" %}
**Start Simple:** Most users never need configuration files. Use command-line flags until you find yourself repeating the same options, then create a config file for convenience.
{% endhint %}
###
###
### Configuration Overview
Gonzo offers three main configuration approaches:
| Method | Complexity | Persistence | Best For |
| ------------------------- | ---------- | ------------- | ------------------------------------ |
| **Command-Line Flags** | Low | Session only | Quick analysis, one-time adjustments |
| **Environment Variables** | Low | Shell session | Personal defaults, API keys |
| **Configuration Files** | Medium | Permanent | Team standards, complex setups |
### Configuration Hierarchy
Understanding how Gonzo resolves configuration:
```
┌─────────────────────────────────────┐
│ 1. Command-Line Flags │ ← Highest priority
│ --log-buffer=5000 │
├─────────────────────────────────────┤
│ 2. Environment Variables │
│ GONZO_LOG_BUFFER=3000 │
├─────────────────────────────────────┤
│ 3. Configuration File │
│ log-buffer: 2000 │
├─────────────────────────────────────┤
│ 4. Built-in Defaults │ ← Lowest priority
│ log-buffer: 1000 │
└─────────────────────────────────────┘
Result: Uses 5000 (command-line flag wins)
```
### Quick Configuration Examples
#### Minimal Setup (No Configuration)
```bash
# Just works - uses sensible defaults
gonzo -f application.log
```
#### Basic Customization (CLI Flags)
```bash
# Common adjustments for specific sessions
gonzo -f /var/log/app.log \
--follow \
--log-buffer=5000 \
--update-interval=2s \
--ai-model="gpt-4"
```
#### Persistent Configuration (Config File)
```yaml
# ~/.config/gonzo/config.yml
files:
- "/var/log/app/*.log"
follow: true
update-interval: 2s
log-buffer: 5000
memory-size: 15000
ai-model: "gpt-4"
```
```bash
# Uses config file automatically
gonzo
```
### Configuration Guide Structure
This section covers all aspects of Gonzo configuration:
#### Configuration File
**Master YAML-based configuration**
Learn how to create and manage configuration files for persistent settings:
* **File location and discovery** - Where Gonzo looks for config files
* **Complete YAML reference** - All available configuration options
* **Environment-specific configs** - Separate configs for dev, staging, production
* **Configuration profiles** - Switch between different setups easily
* **Validation and debugging** - Ensure your config is correct
**Time to master:** 20-30 minutes\
**Prerequisites:** Basic YAML knowledge helpful
***
#### Command Line Reference
**Complete CLI flag documentation**
Comprehensive reference for all command-line options:
* **Core flags** - File input, following, basic operations
* **Performance tuning** - Buffer sizes, update intervals, memory management
* **AI configuration** - Model selection, provider settings
* **Display options** - Interface customization, output control
* **Advanced flags** - Testing, debugging, profiling
**Time to master:** 15-20 minutes\
**Prerequisites:** Basic command-line familiarity
***
#### Advanced Configuration
**Performance tuning and complex setups**
Advanced configuration techniques for production deployments:
* **Performance optimization** - High-volume logs, resource constraints
* **Multi-environment setups** - Dev, staging, production configurations
* **Team configurations** - Shared standards, best practices
* **Integration patterns** - CI/CD, monitoring systems, alerting
* **Troubleshooting configs** - Debug configuration issues
**Time to master:** 30-45 minutes\
**Prerequisites:** Understanding of basic configuration
### Common Configuration Scenarios
#### Development Environment
**Goal:** Fast, responsive analysis with cost-effective AI
```bash
# Quick CLI approach
gonzo -f logs/*.log --follow --ai-model="gpt-3.5-turbo"
# Or create ~/.config/gonzo/dev.yml
files:
- "logs/*.log"
follow: true
update-interval: 1s
log-buffer: 2000
ai-model: "gpt-3.5-turbo"
```
#### Production Monitoring
**Goal:** Reliable, comprehensive monitoring with quality AI analysis
```bash
# Production config: ~/.config/gonzo/prod.yml
files:
- "/var/log/app/*.log"
- "/var/log/nginx/*.log"
follow: true
update-interval: 5s # Conservative updates
log-buffer: 10000 # Large buffer for history
memory-size: 50000 # Ample memory for analysis
ai-model: "gpt-4" # Best quality for production
```
#### CI/CD Integration
**Goal:** Automated log analysis in build pipelines
```bash
# Use environment variables for CI
export GONZO_LOG_BUFFER=5000
export GONZO_UPDATE_INTERVAL=2s
export OPENAI_API_KEY="${CI_OPENAI_KEY}"
# Simple invocation
build-command 2>&1 | gonzo --ai-model="gpt-3.5-turbo"
```
#### High-Volume Log Processing
**Goal:** Handle thousands of log entries per second
```bash
# Optimized for performance
gonzo -f /var/log/high-volume.log \
--follow \
--log-buffer=20000 \
--memory-size=100000 \
--update-interval=10s \
--ai-model="llama3" # Local AI for no API limits
```
### Configuration Best Practices
#### 🎯 **Start Simple, Add Complexity**
1. **Begin with defaults** - Gonzo works well without configuration
2. **Add flags as needed** - Use CLI flags to experiment with settings
3. **Create config when repeating** - Move repeated flags to config files
4. **Separate by environment** - Different configs for dev vs production
#### 📁 **Organize Your Configurations**
```bash
~/.config/gonzo/
├── config.yml # Default configuration
├── dev.yml # Development settings
├── prod.yml # Production settings
├── incident.yml # Incident response settings
└── profiles/
├── security.yml # Security monitoring profile
├── performance.yml # Performance analysis profile
└── debugging.yml # Debugging profile
```
**Usage:**
```bash
# Default config
gonzo
# Specific configuration
gonzo --config ~/.config/gonzo/prod.yml
# Quick profile switching
alias gonzo-dev='gonzo --config ~/.config/gonzo/dev.yml'
alias gonzo-prod='gonzo --config ~/.config/gonzo/prod.yml'
alias gonzo-security='gonzo --config ~/.config/gonzo/profiles/security.yml'
```
#### 🔐 **Secure Configuration Management**
**Do:**
* ✅ Store API keys in environment variables, not config files
* ✅ Use separate configs for different environments
* ✅ Version control config files (without secrets)
* ✅ Document why specific settings were chosen
**Don't:**
* ❌ Commit API keys to version control
* ❌ Share production configs without sanitizing
* ❌ Use production API keys in development
* ❌ Hard-code sensitive information
#### ⚡ **Performance Tuning Strategy**
```bash
# 1. Start with defaults
gonzo -f logs.log
# 2. Monitor resource usage
htop # Check CPU/memory during operation
# 3. Identify bottlenecks
# - High CPU? Increase update-interval
# - High memory? Reduce log-buffer and memory-size
# - Slow AI? Use local models or faster cloud models
# 4. Tune incrementally
gonzo -f logs.log --update-interval=5s # Test slower updates
gonzo -f logs.log --log-buffer=2000 # Test smaller buffer
# 5. Document working configuration
# Save successful settings to config file
```
### Configuration Validation
#### Testing Your Configuration
```bash
# Test configuration syntax
gonzo --config ~/.config/gonzo/config.yml --test-mode
# Dry-run to see what settings would be used
gonzo --config ~/.config/gonzo/config.yml --dry-run
# Verbose output to debug configuration
gonzo --config ~/.config/gonzo/config.yml --verbose
```
#### Common Configuration Issues
**Config file not found:**
```bash
# Check default locations Gonzo searches:
# 1. ./config.yml (current directory)
# 2. ~/.config/gonzo/config.yml
# 3. /etc/gonzo/config.yml
# Specify explicit path
gonzo --config /path/to/config.yml
```
**Settings not taking effect:**
```bash
# Check configuration priority
# CLI flags always override config file
# Example - this uses 5000, not 2000:
# config.yml has: log-buffer: 2000
gonzo --config config.yml --log-buffer=5000
```
**Performance issues:**
```bash
# Configuration too aggressive for system resources
# Solution: Reduce memory/buffer sizes
# From:
log-buffer: 50000
memory-size: 200000
# To:
log-buffer: 10000
memory-size: 30000
```
### Environment-Specific Patterns
#### Development Configuration
```yaml
# dev.yml - Optimized for fast iteration
files:
- "logs/*.log"
- "debug/*.log"
follow: true
update-interval: 1s # Fast updates for development
log-buffer: 2000 # Smaller buffer
memory-size: 10000 # Less memory needed
ai-model: "gpt-3.5-turbo" # Cost-effective
ai-auto-select: true
```
#### Production Configuration
```yaml
# prod.yml - Optimized for reliability and completeness
files:
- "/var/log/app/*.log"
- "/var/log/nginx/*.log"
- "/var/log/database/*.log"
follow: true
update-interval: 5s # Conservative updates
log-buffer: 10000 # Large history buffer
memory-size: 50000 # Ample analysis memory
ai-model: "gpt-4" # Best quality
ai-response-timeout: 60s # Longer timeout for reliability
```
#### Testing/CI Configuration
```yaml
# ci.yml - Optimized for automated analysis
files:
- "build-logs/*.log"
- "test-results/*.log"
follow: false # Batch processing
update-interval: 2s
log-buffer: 5000
ai-model: "gpt-3.5-turbo" # Fast, cost-effective
test-mode: true # CI-friendly output
```
### Configuration Migration
#### Upgrading from CLI to Config File
```bash
# You've been running:
gonzo -f /var/log/app.log \
--follow \
--log-buffer=5000 \
--update-interval=2s \
--ai-model="gpt-4"
# Convert to config file:
cat > ~/.config/gonzo/config.yml << EOF
files:
- "/var/log/app.log"
follow: true
log-buffer: 5000
update-interval: 2s
ai-model: "gpt-4"
EOF
# Now just run:
gonzo
```
#### Team Configuration Standards
```yaml
# team-standard.yml - Shared across team
# Version control this file (without secrets)
# Standard file patterns
file-patterns:
- "*.log"
- "logs/**/*.log"
# Performance standards
update-interval: 2s
log-buffer: 5000
memory-size: 15000
# AI standards (API keys from environment)
ai-model: "gpt-3.5-turbo"
ai-auto-select: true
# Display standards
show-host: true
show-service: true
# Comments explaining choices:
# - 2s update-interval: Balance between responsiveness and resource usage
# - gpt-3.5-turbo: Cost-effective for daily use, upgrade to gpt-4 for incidents
# - 5000 log-buffer: Enough history for correlation without excessive memory
```
### Getting Help with Configuration
**Configuration Resources:**
* **Configuration File Guide** - Complete YAML reference
* **CLI Reference** - All command-line options
* **Advanced Configuration** - Complex setups and tuning
**Community Support:**
* 💬 [GitHub Discussions](https://github.com/control-theory/gonzo/discussions) - Configuration questions
* 🐛 [GitHub Issues](https://github.com/control-theory/gonzo/issues) - Configuration bugs
* 📖 Example configurations in the repository
**Debugging Configuration:**
```bash
# Show current configuration
gonzo --show-config
# Verbose mode for debugging
gonzo --verbose --config myconfig.yml
# Test mode to validate without running
gonzo --test-mode --config myconfig.yml
```
### What's Next?
Ready to configure Gonzo for your needs? Start with the guide that matches your approach:
* **Configuration File** - Create persistent configurations with YAML
* **Command Line Reference** - Master all CLI flags and options
* **Advanced Configuration** - Performance tuning and complex setups
Or explore related topics:
* **Integration Examples** - See configuration in real-world scenarios
* **Advanced Features** - Features to configure and optimize
* **Troubleshooting** - Configuration-related issues
***
**Start with the defaults, configure when needed, optimize for your workflow.** ⚙️ Gonzo's flexible configuration system grows with your needs, from simple CLI flags to sophisticated production deployments.