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

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.

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)

# Just works - uses sensible defaults
gonzo -f application.log

Basic Customization (CLI Flags)

# 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)

# ~/.config/gonzo/config.yml
files:
  - "/var/log/app/*.log"
follow: true
update-interval: 2s
log-buffer: 5000
memory-size: 15000
ai-model: "gpt-4"

# 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

# 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

# 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

# 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

# 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

~/.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:

# 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

# 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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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 - Configuration questions

• 🐛 GitHub Issues - Configuration bugs

• 📖 Example configurations in the repository

Debugging Configuration:

# 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.