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


---

# 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/old-configuration-cover-page.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.