> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/reference/configuration-schema.md). # 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 %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/reference/configuration-schema.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.