# 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

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

### File Format

Gonzo uses YAML format for configuration files.

**Basic structure**:

```yaml
# 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

```yaml
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`)

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

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

**Notes**:

* Override default formats directory
* Must contain `.yaml` format files
* Path can use `~` for home directory

### Complete Example

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

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

```bash
# 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

```yaml
# 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

```yaml
# 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

```yaml
# 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

```yaml
# 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**:

```bash
# 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?

```bash
# 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

{% hint style="info" %}
**Tip**: Start with the example configuration and modify only what you need. This ensures valid syntax and reasonable defaults.
{% endhint %}

{% hint style="warning" %}
**Note**: Changes to the config file require restarting Gonzo. Runtime changes can be made with keyboard shortcuts or flags.
{% endhint %}