# Configuration File

Master YAML-based configuration for persistent Gonzo settings. Configuration files provide a powerful way to manage complex setups, share team standards, and maintain environment-specific configurations.

{% hint style="info" %}
**Quick Start:** Create `~/.config/gonzo/config.yml` and Gonzo will use it automatically. No need to specify the file on every command.
{% endhint %}

### Configuration File Basics

#### File Locations

Gonzo searches for configuration files in this order:

```bash
# 1. Explicit path (highest priority)
gonzo --config /path/to/myconfig.yml

# 2. Current directory
./config.yml
./gonzo.yml

# 3. User config directory (recommended)
~/.config/gonzo/config.yml

# 4. System-wide config
/etc/gonzo/config.yml
```

**Recommended approach:**

```bash
# Create user config directory
mkdir -p ~/.config/gonzo

# Create your configuration file
cat > ~/.config/gonzo/config.yml << 'EOF'
# Your Gonzo configuration
files:
  - "/var/log/app.log"
follow: true
update-interval: 2s
EOF
```

#### Basic Configuration Structure

```yaml
# ~/.config/gonzo/config.yml

# File input configuration
files:
  - "/var/log/app.log"
  - "/var/log/nginx/*.log"
follow: true

# Performance settings
update-interval: 2s
log-buffer: 5000
memory-size: 15000

# AI configuration
ai-model: "gpt-4"

# Display options
show-host: true
show-service: true
```

### Complete Configuration Reference

#### File Input Configuration

**Control which logs to analyze:**

```yaml
# Single file
files:
  - "/var/log/app.log"

# Multiple specific files
files:
  - "/var/log/app.log"
  - "/var/log/error.log"
  - "/var/log/debug.log"

# Glob patterns
files:
  - "/var/log/*.log"
  - "/var/log/app-*.log"
  - "logs/**/*.log"

# Mixed approaches
files:
  - "/var/log/app.log"          # Specific file
  - "/var/log/nginx/*.log"      # Glob pattern
  - "/home/user/debug.log"      # User directory

# Follow mode (like tail -f)
follow: true                     # Enable following
follow: false                    # Disable (default for single files)
```

**Options:**

* `files` (array of strings) - Files or glob patterns to read
* `follow` (boolean) - Enable real-time following (default: `false`)

#### Performance Configuration

**Tune Gonzo's performance characteristics:**

```yaml
# Update frequency
update-interval: 2s              # How often to refresh display
                                 # Options: 1s, 2s, 5s, 10s, 30s
                                 # Lower = more responsive, higher CPU
                                 # Higher = less CPU, less responsive

# Buffer sizes
log-buffer: 5000                 # Maximum log entries to keep in memory
                                 # Default: 1000
                                 # Higher = more history, more memory
                                 # Lower = less memory, less history

memory-size: 15000               # Maximum word frequency entries
                                 # Default: 10000
                                 # Higher = more pattern tracking
                                 # Lower = less memory usage

# Processing options
batch-size: 100                  # Number of logs to process per batch
                                 # Default: 100
                                 # Higher = more efficient, higher latency
                                 # Lower = more responsive, less efficient
```

**Tuning Guidelines:**

{% tabs %}
{% tab title="Development" %}

```yaml
# Optimized for fast iteration
update-interval: 1s              # Fast updates
log-buffer: 2000                # Moderate history
memory-size: 10000              # Sufficient for development
```

{% endtab %}

{% tab title="Production Monitoring" %}

```yaml
# Optimized for reliability and history
update-interval: 5s              # Conservative updates
log-buffer: 10000               # Large history buffer
memory-size: 50000              # Comprehensive pattern tracking
```

{% endtab %}

{% tab title="High Volume" %}

```yaml
# Optimized for processing speed
update-interval: 10s             # Slow updates to reduce overhead
log-buffer: 20000               # Large buffer for throughput
memory-size: 100000             # Extensive pattern capacity
batch-size: 500                 # Large batches for efficiency
```

{% endtab %}

{% tab title="Resource Constrained" %}

```yaml
# Optimized for minimal resource usage
update-interval: 5s              # Moderate updates
log-buffer: 1000                # Minimal buffer
memory-size: 5000               # Reduced memory footprint
batch-size: 50                  # Smaller batches
```

{% endtab %}
{% endtabs %}

#### AI Configuration

**Configure AI analysis features:**

```yaml
# Basic AI settings
ai-model: "gpt-4"                # Default AI model to use
                                 # Options: "gpt-4", "gpt-3.5-turbo", 
                                 # "llama3", "mistral", etc.

ai-auto-select: true             # Automatically select best available model
                                 # Default: true

# AI provider configuration (usually via environment variables)
# These are typically set as env vars, not in config file
# OPENAI_API_KEY="sk-..."
# OPENAI_API_BASE="https://api.openai.com/v1"

# AI performance settings
ai-context-size: 4000            # Maximum context tokens for AI
                                 # Default: 4000
                                 # Higher = better context, more cost
                                 # Lower = less cost, less context

ai-response-timeout: 30s         # Timeout for AI responses
                                 # Default: 30s
                                 # Increase for complex analysis

ai-max-retries: 3                # Retry failed AI requests
                                 # Default: 3

# AI cost management
ai-daily-token-limit: 100000     # Optional daily token budget
ai-warn-at-usage: 80000          # Warning threshold (80%)
```

**AI Configuration Examples:**

{% tabs %}
{% tab title="OpenAI Production" %}

```yaml
# High-quality AI for critical analysis
ai-model: "gpt-4"
ai-context-size: 8000            # Large context for complex issues
ai-response-timeout: 60s         # Allow time for thorough analysis
ai-max-retries: 5                # Ensure reliability
```

{% endtab %}

{% tab title="Cost-Optimized" %}

```yaml
# Balance cost and quality
ai-model: "gpt-3.5-turbo"
ai-context-size: 2000            # Smaller context to reduce tokens
ai-response-timeout: 30s
ai-daily-token-limit: 50000      # Cost control
```

{% endtab %}

{% tab title="Local AI" %}

```yaml
# Privacy-focused local AI
ai-model: "llama3"               # Local Ollama model
ai-context-size: 4000
ai-response-timeout: 60s         # Local inference can be slower
# No token limits needed with local AI
```

{% endtab %}
{% endtabs %}

#### Display Configuration

**Customize the interface appearance:**

```yaml
# Column visibility
show-host: true                  # Show host/source column
                                 # Default: false
show-service: true               # Show service column
                                 # Default: false

# Color and formatting
no-color: false                  # Disable color output
                                 # Default: false
                                 # Useful for logging output to files

# Output options
json-output: false               # Output as JSON instead of TUI
                                 # Default: false
                                 # Useful for scripting

quiet: false                     # Suppress non-essential output
                                 # Default: false
```

#### Stop Words Configuration

**Filter common or domain-specific words from frequency analysis:**

```yaml
# Stop words configuration
stop-words:
  - "debug"                      # Filter log-specific terms
  - "info"
  - "warning"
  - "error"
  - "log"
  - "message"
  - "timestamp"
  - "level"
  - "springframework"            # Filter framework noise
  - "hibernate"
  - "GET"                        # Filter HTTP-related terms
  - "POST"
  - "HTTP"
```

**How Stop Words Work:**

* Filters words from Word Frequency panel analysis
* Case-insensitive matching ("ERROR" and "error" treated the same)
* Added to built-in English stop words (60+ common words like "the", "and", "for")
* Does not affect log display or filtering - only frequency analysis
* Changes take effect immediately when logs are processed

**Use Cases:**

{% tabs %}
{% tab title="Web Server Logs" %}

```yaml
# Filter HTTP-related terms to focus on actual content
stop-words:
  - "GET"
  - "POST"
  - "PUT"
  - "DELETE"
  - "HTTP"
  - "HTTPS"
  - "status"
  - "request"
  - "response"
```

{% endtab %}

{% tab title="Application Logs" %}

```yaml
# Filter framework and logging noise
stop-words:
  - "log"
  - "message"
  - "level"
  - "timestamp"
  - "logger"
  - "springframework"
  - "hibernate"
  - "slf4j"
```

{% endtab %}

{% tab title="Error Analysis" %}

```yaml
# Focus on actual errors, not stack trace noise
stop-words:
  - "stack"
  - "trace"
  - "at"
  - "caused"
  - "exception"
  - "error"
  - "line"
```

{% endtab %}
{% endtabs %}

#### OTLP Configuration

**OpenTelemetry Protocol receiver settings:**

```yaml
# Enable OTLP receiver
otlp-enabled: true               # Start OTLP receiver
                                 # Default: false

# OTLP ports
otlp-grpc-port: 4317             # gRPC endpoint port
                                 # Default: 4317
otlp-http-port: 4318             # HTTP endpoint port  
                                 # Default: 4318

# OTLP processing
otlp-batch-size: 100             # Batch size for OTLP logs
                                 # Default: 100
```

**OTLP Configuration Example:**

```yaml
# Full OTLP receiver setup
otlp-enabled: true
otlp-grpc-port: 5317             # Custom ports to avoid conflicts
otlp-http-port: 5318

# Also analyze local files
files:
  - "/var/log/backup.log"
follow: true

# Performance for OTLP ingestion
log-buffer: 20000                # Large buffer for OTLP volume
update-interval: 5s              # Conservative updates
```

#### Development and Testing Options

**Configuration for testing and development:**

```yaml
# Testing mode
test-mode: true                  # Enable test mode
                                 # Default: false
                                 # Runs without full TUI, good for CI/CD

# Verbose output
verbose: false                   # Enable verbose logging
                                 # Default: false
                                 # Useful for debugging

# Dry run
dry-run: false                   # Show what would be done without doing it
                                 # Default: false
                                 # Good for validating configuration
```

### Complete Configuration Examples

#### Personal Development Setup

```yaml
# ~/.config/gonzo/config.yml
# Personal development configuration

# Development logs
files:
  - "logs/*.log"
  - "debug/*.log"
  - "test-results/*.log"

# Follow for live development
follow: true

# Fast updates for immediate feedback
update-interval: 1s

# Moderate buffers for development
log-buffer: 2000
memory-size: 10000

# Cost-effective AI
ai-model: "gpt-3.5-turbo"
ai-auto-select: true

# Show full context
show-host: true
show-service: true

# Comments are preserved for documentation
# This config optimized for: Fast iteration, cost control
```

#### Production Monitoring

```yaml
# ~/.config/gonzo/prod.yml
# Production monitoring configuration

# Production log locations
files:
  - "/var/log/app/*.log"
  - "/var/log/nginx/access.log"
  - "/var/log/nginx/error.log"
  - "/var/log/postgresql/*.log"

# Real-time monitoring
follow: true

# Conservative updates for reliability
update-interval: 5s

# Large buffers for comprehensive analysis
log-buffer: 10000
memory-size: 50000

# Best quality AI for production
ai-model: "gpt-4"
ai-context-size: 8000
ai-response-timeout: 60s
ai-max-retries: 5

# Full visibility
show-host: true
show-service: true

# Production notes:
# - Uses gpt-4 for best analysis quality
# - Large buffers for comprehensive history
# - Conservative update interval for reliability
# - Monitors all critical services
```

#### CI/CD Pipeline

```yaml
# config/gonzo-ci.yml
# CI/CD automated analysis configuration

# Build and test logs
files:
  - "build-logs/*.log"
  - "test-results/*.log"
  - "integration-tests/*.log"

# Batch processing (not following)
follow: false

# Moderate performance
update-interval: 2s
log-buffer: 5000

# Fast, cost-effective AI
ai-model: "gpt-3.5-turbo"
ai-context-size: 2000
ai-response-timeout: 30s

# CI-friendly output
test-mode: true                  # Non-interactive mode
json-output: false               # Keep TUI output for logs
quiet: false                     # Show all output

# Notes:
# - test-mode enables CI-friendly operation
# - Uses cost-effective AI model
# - Processes logs in batch, not real-time
```

#### Team Standard Configuration

```yaml
# team-standard.yml
# Shared configuration across development team
# Version control this file

# Standard log locations (relative paths)
files:
  - "logs/*.log"

# Standard performance settings
update-interval: 2s
log-buffer: 5000
memory-size: 15000

# Team AI standard
ai-model: "gpt-3.5-turbo"        # Cost-effective default
ai-auto-select: true             # Allow auto-upgrade when needed

# Display standards
show-service: true               # Always show service context

# Team notes:
# - API keys managed via environment variables (not in config)
# - Use gpt-4 for incident response (override with CLI flag)
# - Update this file through pull requests
# - Document reasoning for any changes

# Last updated: 2024-01-15
# Updated by: DevOps team
# Reason: Increased log-buffer for better analysis
```

#### Security Monitoring

```yaml
# ~/.config/gonzo/security.yml
# Security-focused monitoring configuration

# Security-relevant logs
files:
  - "/var/log/auth.log"
  - "/var/log/nginx/access.log"
  - "/var/log/fail2ban.log"
  - "/var/log/app/security.log"

# Real-time monitoring for security
follow: true
update-interval: 2s              # Responsive for security events

# Large buffers for security analysis
log-buffer: 15000
memory-size: 75000

# Best AI for security analysis
ai-model: "gpt-4"
ai-context-size: 8000
ai-response-timeout: 60s

# Full context for security investigations
show-host: true
show-service: true

# Security notes:
# - Monitor all authentication and access logs
# - Use gpt-4 for accurate threat assessment
# - Large buffers for pattern analysis
# - Real-time monitoring for rapid response
```

### Configuration Profiles

#### Managing Multiple Configurations

Create different profiles for different scenarios:

```bash
# Directory structure
~/.config/gonzo/
├── config.yml              # Default configuration
├── dev.yml                 # Development profile
├── prod.yml                # Production profile
├── security.yml            # Security monitoring
├── performance.yml         # Performance analysis
└── incident.yml            # Incident response

# Usage with aliases
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/security.yml'
alias gonzo-incident='gonzo --config ~/.config/gonzo/incident.yml'

# Quick switching
gonzo-dev        # Use development config
gonzo-prod       # Use production config
gonzo-security   # Use security monitoring config
```

#### Profile Inheritance Strategy

```yaml
# base.yml - Shared settings
# Include common settings here

update-interval: 2s
log-buffer: 5000
show-service: true

# Then extend in specific profiles:
# dev.yml includes base settings + overrides
# prod.yml includes base settings + overrides
# Use YAML anchors for inheritance (advanced)
```

### Configuration Validation

#### Testing Your Configuration

```bash
# Validate configuration syntax
gonzo --config myconfig.yml --dry-run

# Show what configuration would be used
gonzo --config myconfig.yml --show-config

# Test with verbose output
gonzo --config myconfig.yml --verbose

# Test mode for CI/CD validation
gonzo --config myconfig.yml --test-mode
```

#### Common Configuration Errors

**Invalid YAML Syntax:**

```yaml
# ❌ Wrong - improper indentation
files:
- "/var/log/app.log"
  - "/var/log/error.log"    # Inconsistent indentation

# ✅ Correct - consistent indentation
files:
  - "/var/log/app.log"
  - "/var/log/error.log"
```

**Invalid Data Types:**

```yaml
# ❌ Wrong - string instead of number
log-buffer: "5000"           # Should be number, not string

# ✅ Correct - proper types
log-buffer: 5000             # Number
follow: true                 # Boolean
files:                       # Array
  - "/var/log/app.log"
```

**Invalid Values:**

```yaml
# ❌ Wrong - invalid duration format
update-interval: 2seconds    # Invalid format

# ✅ Correct - proper duration syntax
update-interval: 2s          # Valid: 1s, 2s, 5s, 10s, 30s, 1m
```

### Configuration Best Practices

#### 🎯 **Organization**

```yaml
# Group related settings with comments
# ===== File Input Configuration =====
files:
  - "/var/log/app.log"
follow: true

# ===== Performance Settings =====
update-interval: 2s
log-buffer: 5000
memory-size: 15000

# ===== AI Configuration =====
ai-model: "gpt-4"
ai-context-size: 4000

# ===== Display Options =====
show-host: true
show-service: true
```

#### 🔒 **Security**

```yaml
# ✅ Good - API keys in environment variables
ai-model: "gpt-4"
# OPENAI_API_KEY set via environment variable

# ❌ Bad - API keys in config file
# ai-api-key: "sk-secret-key-here"  # NEVER DO THIS

# ✅ Good - Document expectations
# Required environment variables:
# - OPENAI_API_KEY: OpenAI API key for AI features
# - GONZO_LOG_PATH: Override default log path
```

#### 📝 **Documentation**

```yaml
# Document your configuration choices
# Last updated: 2024-01-15
# Owner: DevOps Team
# Purpose: Production monitoring configuration

# Performance tuning reasoning:
# - update-interval: 5s chosen to balance responsiveness with CPU usage
# - log-buffer: 10000 provides 10-15 minutes of history at typical volume
# - memory-size: 50000 supports comprehensive pattern analysis

files:
  - "/var/log/app/*.log"
update-interval: 5s
log-buffer: 10000
memory-size: 50000
```

#### 🔄 **Version Control**

```bash
# Create a repository for team configurations
mkdir gonzo-configs
cd gonzo-configs
git init

# Add configurations
cp ~/.config/gonzo/team-standard.yml .
cp ~/.config/gonzo/prod.yml .

# Create README documenting each config
cat > README.md << 'EOF'
# Gonzo Configurations

## team-standard.yml
Default configuration for development team

## prod.yml  
Production monitoring configuration
EOF

git add .
git commit -m "Initial Gonzo configurations"
```

### Advanced Configuration Patterns

#### Environment Variable Substitution

```yaml
# Use environment variables in config (if supported)
files:
  - "${LOG_DIR}/*.log"
  - "${APP_LOG_PATH}/application.log"

ai-model: "${GONZO_AI_MODEL:-gpt-3.5-turbo}"  # Default if not set
```

#### Conditional Configuration

```bash
# Use different configs based on environment
GONZO_ENV="${ENVIRONMENT:-development}"
CONFIG_FILE="~/.config/gonzo/${GONZO_ENV}.yml"

gonzo --config "$CONFIG_FILE"
```

#### Configuration Generation

```bash
#!/bin/bash
# generate-config.sh - Dynamic configuration generation

cat > ~/.config/gonzo/config.yml << EOF
# Generated configuration
# Environment: ${ENVIRONMENT}
# Generated: $(date)

files:
  - "${LOG_PATH}/*.log"

update-interval: ${UPDATE_INTERVAL:-2s}
log-buffer: ${LOG_BUFFER:-5000}
ai-model: "${AI_MODEL:-gpt-3.5-turbo}"
EOF
```

### Troubleshooting Configuration

#### Configuration Not Loading

```bash
# Check if config file exists
ls -la ~/.config/gonzo/config.yml

# Check file permissions
chmod 644 ~/.config/gonzo/config.yml

# Test with explicit path
gonzo --config ~/.config/gonzo/config.yml

# Check for YAML syntax errors
# Use a YAML validator or Python
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
```

#### Settings Not Taking Effect

```bash
# Remember: CLI flags override config file
# If running: gonzo --log-buffer=3000
# Config file log-buffer setting is ignored

# Check actual configuration being used
gonzo --show-config

# Use verbose mode to see configuration loading
gonzo --verbose
```

#### Performance Issues

```bash
# Config might be too aggressive for your system
# Symptoms: High CPU, high memory usage

# Solution: Start with conservative settings
update-interval: 5s              # Slower updates
log-buffer: 2000                # Smaller buffer
memory-size: 10000              # Less memory

# Then gradually increase if needed
```

### What's Next?

Now that you understand configuration files, explore related topics:

* **Command Line Reference** - All CLI flags that can override config settings
* **Advanced Configuration** - Complex setups and optimization techniques
* **Integration Examples** - Configuration in real-world scenarios

Or start creating your own configurations:

```bash
# Create your first config file
mkdir -p ~/.config/gonzo
cat > ~/.config/gonzo/config.yml << 'EOF'
# My Gonzo Configuration
files:
  - "/var/log/app.log"
follow: true
update-interval: 2s
log-buffer: 5000
ai-model: "gpt-3.5-turbo"
EOF

# Test it
gonzo
```

***

**Master configuration files to maintain consistent, powerful Gonzo setups!** 📝 From simple personal configs to sophisticated team standards, configuration files make Gonzo work exactly how you need it.


---

# 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/controltheory-documentation/gonzo-docs/configuration/configuration-file.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.