Configuration Schema

Complete reference for Gonzo's configuration file format. This guide documents all available configuration options and their valid values.

Configuration File Location

Default location: ~/.config/gonzo/config.yml

Custom location: Specify with --config flag

gonzo --config /path/to/config.yml

File Format

Gonzo uses YAML format for configuration files.

Basic structure:

# Input configuration
files: []
follow: false

# Performance settings
update-interval: 1s
log-buffer: 1000
memory-size: 10000

# Display settings
skin: default

# AI configuration
ai-model: ""

# OTLP receiver
otlp:
  enabled: false
  grpc-port: 4317
  http-port: 4318

Complete Schema

Input Configuration

files

Type: array of strings Default: [] (empty, uses stdin) Description: List of log files or glob patterns to read

files:
  - "/var/log/app.log"
  - "/var/log/error.log"
  - "/var/log/*.log"

Notes:

• Supports glob patterns

• Can specify multiple files

• Paths can be relative or absolute

• Empty array uses stdin

follow

Type: boolean Default: false Description: Follow log files in real-time (like tail -f)

follow: true

Notes:

• Only applies to file input

• When true, watches files for new content

• Useful for monitoring live logs

Performance Settings

update-interval

Type: duration Default: "1s" Valid values: Any Go duration string Description: How often the dashboard updates

update-interval: 2s

Examples:

• "500ms" - Half second

• "1s" - One second (default)

• "2s" - Two seconds

• "5s" - Five seconds

• "10s" - Ten seconds

Notes:

• Lower values = more responsive but higher CPU

• Higher values = lower CPU but less responsive

• Can be changed at runtime with u/U keys

log-buffer

Type: integer Default: 1000 Valid range: 1 to 100000 Description: Maximum number of log entries to keep in memory

log-buffer: 2000

Notes:

• Circular buffer (old logs evicted when full)

• Higher values use more memory

• Lower values may lose old logs faster

• Consider log volume when setting

memory-size

Type: integer Default: 10000 Valid range: 100 to 1000000 Description: Maximum number of words to track for frequency analysis

memory-size: 15000

Notes:

• Affects Word Frequency panel

• Higher values track more unique words

• Lower values use less memory

• LRU eviction when limit reached

Display Settings

skin

Type: string Default: "default" Valid values: Any installed skin name Description: Color scheme/theme to use

skin: dracula

Built-in skins:

Dark themes:

• default - Gonzo default dark

• controltheory-dark - ControlTheory branded

• dracula - Dracula theme

• gruvbox - Gruvbox dark

• monokai - Monokai

• nord - Nord theme

• solarized-dark - Solarized dark

Light themes:

• controltheory-light - ControlTheory branded

• github-light - GitHub light

• solarized-light - Solarized light

• vs-code-light - VS Code light

• spring - Spring theme

Notes:

• Custom skins go in ~/.config/gonzo/skins/

• Can be changed via command line: --skin=NAME

AI Configuration

ai-model

Type: string Default: "" (auto-select best available) Description: AI model to use for log analysis

ai-model: "gpt-4"

Common values:

• "" - Auto-select (recommended)

• "gpt-4" - OpenAI GPT-4

• "gpt-3.5-turbo" - OpenAI GPT-3.5

• "llama3" - Ollama Llama 3

• "mistral" - Ollama Mistral

• Model names from your AI provider

Notes:

• Requires OPENAI_API_KEY environment variable

• Can be overridden with --ai-model flag

• Can be changed at runtime with m key

OTLP Receiver Configuration

otlp.enabled

Type: boolean Default: false Description: Enable OTLP log receiver

otlp:
  enabled: true

Notes:

• Starts gRPC and HTTP servers

• Required for receiving OTLP logs

• Can be enabled via --otlp-enabled flag

otlp.grpc-port

Type: integer Default: 4317 Valid range: 1024 to 65535 Description: Port for OTLP gRPC receiver

otlp:
  enabled: true
  grpc-port: 5317

Notes:

• Standard OTLP port is 4317

• Change if port conflict exists

• Requires otlp.enabled: true

otlp.http-port

Type: integer Default: 4318 Valid range: 1024 to 65535 Description: Port for OTLP HTTP receiver

otlp:
  enabled: true
  http-port: 5318

Notes:

• Standard OTLP HTTP port is 4318

• Change if port conflict exists

• Requires otlp.enabled: true

Advanced Configuration

test-mode

Type: boolean Default: false Description: Run without TTY for testing

test-mode: true

Notes:

• For automated testing only

• Disables TUI

• Not for normal use

formats-dir

Type: string Default: "~/.config/gonzo/formats" Description: Directory containing custom format definitions

formats-dir: "/custom/path/to/formats"

Notes:

• Override default formats directory

• Must contain .yaml format files

• Path can use ~ for home directory

Complete Example

# ~/.config/gonzo/config.yml
# Complete Gonzo configuration example

# ===== Input Configuration =====
# Files to read (supports glob patterns)
files:
  - "/var/log/app.log"
  - "/var/log/error.log"
  - "/var/log/nginx/*.log"

# Follow files in real-time (like tail -f)
follow: true

# ===== Performance Settings =====
# Dashboard update frequency
# Options: 500ms, 1s, 2s, 5s, 10s
update-interval: 2s

# Maximum log entries to keep in buffer
# Higher = more history, more memory
log-buffer: 2000

# Maximum unique words to track
# Higher = more words tracked, more memory
memory-size: 15000

# ===== Display Settings =====
# Color scheme (built-in or custom)
# Options: default, dracula, nord, monokai, etc.
skin: dracula

# ===== AI Configuration =====
# AI model for log analysis
# Empty string = auto-select best available
# Examples: "gpt-4", "gpt-3.5-turbo", "llama3"
ai-model: "gpt-4"

# ===== OTLP Receiver =====
# OpenTelemetry Protocol log receiver
otlp:
  # Enable OTLP receiver
  enabled: true
  
  # gRPC port (standard: 4317)
  grpc-port: 4317
  
  # HTTP port (standard: 4318)
  http-port: 4318

# ===== Advanced Settings =====
# Custom formats directory
# formats-dir: "~/.config/gonzo/formats"

# Test mode (for automated testing)
# test-mode: false

Validation

Schema Validation

Gonzo validates configuration on startup:

Valid config: Gonzo starts normally Invalid config: Error message explains issue

Common validation errors:

• Invalid YAML syntax

• Unknown configuration keys

• Invalid value types

• Out-of-range values

Testing Configuration

Test your configuration:

# Try loading config
gonzo --config config.yml --help

# If no errors, config is valid

Environment Variable Overrides

Environment variables override config file:

Config Key	Environment Variable
files	GONZO_FILES
follow	GONZO_FOLLOW
update-interval	GONZO_UPDATE_INTERVAL
log-buffer	GONZO_LOG_BUFFER
memory-size	GONZO_MEMORY_SIZE
ai-model	GONZO_AI_MODEL
otlp.enabled	GONZO_OTLP_ENABLED
otlp.grpc-port	GONZO_OTLP_GRPC_PORT
otlp.http-port	GONZO_OTLP_HTTP_PORT

See Environment Variables for details.

Command Line Flag Overrides

Command line flags override both config file and environment variables:

# Config file says follow: false
# This overrides it:
gonzo --config config.yml --follow

# Config file says update-interval: 2s
# This overrides it:
gonzo --config config.yml --update-interval=5s

Priority (highest to lowest):

1. Command line flags

2. Environment variables

3. Configuration file

4. Default values

Configuration Best Practices

Production Use

# Optimized for production monitoring
files:
  - "/var/log/production/*.log"
follow: true
update-interval: 2s  # Balance responsiveness and CPU
log-buffer: 5000     # Keep more history
memory-size: 20000   # Track more words
skin: default        # Consistent appearance

Development Use

# Optimized for local development
files:
  - "/var/log/app.log"
  - "/tmp/debug.log"
follow: true
update-interval: 1s  # Fast updates
log-buffer: 1000     # Less history needed
memory-size: 10000   # Standard tracking
skin: dracula        # Personal preference

Resource-Constrained

# Optimized for low-resource systems
files:
  - "/var/log/app.log"
follow: true
update-interval: 5s  # Reduce CPU
log-buffer: 500      # Minimal memory
memory-size: 5000    # Minimal tracking
skin: default

OTLP Receiver

# Optimized for OTLP log ingestion
# No files needed - receives via network
otlp:
  enabled: true
  grpc-port: 4317
  http-port: 4318
update-interval: 1s  # Responsive for live logs
log-buffer: 2000     # Buffer network logs
memory-size: 15000

Troubleshooting

Config Not Loading

Symptom: Settings ignored

Checks:

# Verify file exists
ls -la ~/.config/gonzo/config.yml

# Check YAML syntax
cat ~/.config/gonzo/config.yml

# Specify explicitly
gonzo --config ~/.config/gonzo/config.yml

Invalid YAML

Symptom: Parse error on startup

Solution:

• Check indentation (use spaces, not tabs)

• Verify colons have spaces after them

• Ensure strings with special chars are quoted

• Use YAML validator online

Values Not Applied

Check priority:

1. Is there a command line flag overriding?

2. Is there an environment variable set?

3. Is the config file being loaded?

# Check environment
env | grep GONZO

# Clear environment if needed
unset GONZO_UPDATE_INTERVAL

Related Documentation

• Environment Variables - Environment variable reference

• CLI Reference - Command line options

• Configuration File Guide - Detailed configuration guide

Tip: Start with the example configuration and modify only what you need. This ensures valid syntax and reasonable defaults.

Note: Changes to the config file require restarting Gonzo. Runtime changes can be made with keyboard shortcuts or flags.