ControlTheory Website

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.

Quick Start: Create ~/.config/gonzo/config.yml and Gonzo will use it automatically. No need to specify the file on every command.

Configuration File Basics

File Locations

Gonzo searches for configuration files in this order:

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

# 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

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

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

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

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

AI Configuration

Configure AI analysis features:

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

# 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

Display Configuration

Customize the interface appearance:

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

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

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

OTLP Configuration

OpenTelemetry Protocol receiver settings:

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

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

# 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

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

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

# 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

# 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

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

# 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

# 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

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

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

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

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

# 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

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

# 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

# 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

# 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

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

gonzo --config "$CONFIG_FILE"

Configuration Generation

#!/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

# 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

# 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

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

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

PreviousConfigurationNextCommand Line Reference

Last updated