gonzo

gonzo

Gonzo! The Go based TUI log analysis tool

Stars: 1180

Visit
 screenshot

Gonzo is a powerful, real-time log analysis terminal UI tool inspired by k9s. It allows users to analyze log streams with beautiful charts, AI-powered insights, and advanced filtering directly from the terminal. The tool provides features like live streaming log processing, OTLP support, interactive dashboard with real-time charts, advanced filtering options including regex support, and AI-powered insights such as pattern detection, anomaly analysis, and root cause suggestions. Users can also configure AI models from providers like OpenAI, LM Studio, and Ollama for intelligent log analysis. Gonzo is built with Bubble Tea, Lipgloss, Cobra, Viper, and OpenTelemetry, following a clean architecture with separate modules for TUI, log analysis, frequency tracking, OTLP handling, and AI integration.

README:

Gonzo - The Go based TUI for log analysis

Gonzo Mascot

Go Version License: MIT PRs Welcome

A powerful, real-time log analysis terminal UI inspired by k9s. Analyze log streams with beautiful charts, AI-powered insights, and advanced filtering - all from your terminal.

See it in action

Gonzo Walkthrough

Main Dashboard

Gonzo Main Dashboard

Stats and Info

Gonzo Stats

Everyone loves a heatmap

Gonzo Heatmap

โœจ Features

๐ŸŽฏ Real-Time Analysis

  • Live streaming - Process logs as they arrive from stdin, files, or network
  • OTLP native - First-class support for OpenTelemetry log format
  • OTLP receiver - Built-in gRPC server to receive logs via OpenTelemetry protocol
  • Format detection - Automatically detects JSON, logfmt, and plain text
  • Severity tracking - Color-coded severity levels with distribution charts

๐Ÿ“ˆ Interactive Dashboard

  • k9s-inspired layout - Familiar 2x2 grid interface
  • Real-time charts - Word frequency, attributes, severity distribution, and time series
  • Keyboard + mouse navigation - Vim-style shortcuts plus click-to-navigate and scroll wheel support
  • Smart log viewer - Auto-scroll with intelligent pause/resume behavior
  • Fullscreen log viewer - Press f to open a dedicated fullscreen modal for log browsing with all navigation features
  • Global pause control - Spacebar pauses entire dashboard while buffering logs
  • Modal details - Deep dive into individual log entries with expandable views
  • Log Counts analysis - Detailed modal with heatmap visualization, pattern analysis by severity, and service distribution
  • AI analysis - Get intelligent insights about log patterns and anomalies with configurable models

๐Ÿ” Advanced Filtering

  • Regex support - Filter logs with regular expressions
  • Attribute search - Find logs by specific attribute values
  • Severity filtering - Focus on errors, warnings, or specific log levels
  • Interactive selection - Click or keyboard navigate to explore logs

๐Ÿค– AI-Powered Insights

  • Pattern detection - Automatically identify recurring issues
  • Anomaly analysis - Spot unusual patterns in your logs
  • Root cause suggestions - Get AI-powered debugging assistance
  • Configurable models - Choose from GPT-4, GPT-3.5, or any custom model
  • Multiple providers - Works with OpenAI, LM Studio, Ollama, or any OpenAI-compatible API
  • Local AI support - Run completely offline with local models

๐Ÿš€ Quick Start

Installation

Using Go

go install github.com/control-theory/gonzo/cmd/gonzo@latest

Using Homebrew (macOS/Linux)

brew install gonzo

Download Binary

Download the latest release for your platform from the releases page.

Using Nix package manager (beta support)

nix run github:control-theory/gonzo

Build from Source

git clone https://github.com/control-theory/gonzo.git
cd gonzo
make build

๐Ÿ“– Usage

Basic Usage

# Read logs directly from files
gonzo -f application.log

# Read from multiple files
gonzo -f application.log -f error.log -f debug.log

# Use glob patterns to read multiple files
gonzo -f "/var/log/*.log"
gonzo -f "/var/log/app/*.log" -f "/var/log/nginx/*.log"

# Follow log files in real-time (like tail -f)
gonzo -f /var/log/app.log --follow
gonzo -f "/var/log/*.log" --follow

# Analyze logs from stdin (traditional way)
cat application.log | gonzo

# Stream logs from kubectl
kubectl logs -f deployment/my-app | gonzo

# Follow system logs
tail -f /var/log/syslog | gonzo

# Analyze Docker container logs
docker logs -f my-container 2>&1 | gonzo

# With AI analysis (requires API key)
export OPENAI_API_KEY=sk-your-key-here
gonzo -f application.log --ai-model="gpt-4"

OTLP Network Receiver

Gonzo can receive logs directly via OpenTelemetry Protocol (OTLP) over both gRPC and HTTP:

# Start Gonzo as an OTLP receiver (both gRPC on port 4317 and HTTP on port 4318)
gonzo --otlp-enabled

# Use custom ports
gonzo --otlp-enabled --otlp-grpc-port=5317 --otlp-http-port=5318

# gRPC endpoint: localhost:4317
# HTTP endpoint: http://localhost:4318/v1/logs

Example: OpenTelemetry Collector Configuration

Using gRPC:

exporters:
  otlp/gonzo_grpc:
    endpoint: localhost:4317
    tls:
      insecure: true

service:
  pipelines:
    logs:
      receivers: [your_receivers]
      processors: [your_processors]
      exporters: [otlp/gonzo_grpc]

Using HTTP:

exporters:
  otlphttp/gonzo_http:
    endpoint: http://localhost:4318/v1/logs

service:
  pipelines:
    logs:
      receivers: [your_receivers]
      processors: [your_processors]
      exporters: [otlphttp/gonzo_http]

Example: Python Application

Using gRPC:

from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter

exporter = OTLPLogExporter(
    endpoint="localhost:4317",
    insecure=True
)

Using HTTP:

from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

exporter = OTLPLogExporter(
    endpoint="http://localhost:4318/v1/logs",
)

See examples/send_otlp_logs.py for a complete example.

With AI Analysis

# Auto-select best available model (recommended) - file input
export OPENAI_API_KEY=sk-your-key-here
gonzo -f logs.json

# Or specify a particular model - file input
export OPENAI_API_KEY=sk-your-key-here
gonzo -f logs.json --ai-model="gpt-4"

# Follow logs with AI analysis
export OPENAI_API_KEY=sk-your-key-here
gonzo -f "/var/log/app.log" --follow --ai-model="gpt-4"

# Using local LM Studio (auto-selects first available)
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"
gonzo -f logs.json

# Using Ollama (auto-selects best model like gpt-oss:20b)
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
gonzo -f logs.json --follow

# Traditional stdin approach still works
export OPENAI_API_KEY=sk-your-key-here
cat logs.json | gonzo --ai-model="gpt-4"

Keyboard Shortcuts

Navigation

Key/Mouse Action
Tab / Shift+Tab Navigate between panels
Mouse Click Click on any section to switch to it
โ†‘/โ†“ or k/j Move selection up/down
Mouse Wheel Scroll up/down to navigate selections
โ†/โ†’ or h/l Horizontal navigation
Enter View log details or open analysis modal (Counts section)
ESC Close modal/cancel

Actions

Key Action
Space Pause/unpause entire dashboard
/ Enter filter mode (regex supported)
s Search and highlight text in logs
f Open fullscreen log viewer modal
c Toggle Host/Service columns in log view
r Reset all data (manual reset)
u / U Cycle update intervals (forward/backward)
i AI analysis (in detail view)
m Switch AI model (shows available models)
? / h Show help
q / Ctrl+C Quit

Log Viewer Navigation

Key Action
Home Jump to top of log buffer (stops auto-scroll)
End Jump to latest logs (resumes auto-scroll)
PgUp / PgDn Navigate by pages (10 entries at a time)
โ†‘/โ†“ or k/j Navigate entries with smart auto-scroll

AI Chat (in log detail modal)

Key Action
c Start chat with AI about current log
Tab Switch between log details and chat pane
m Switch AI model (works in modal too)

Log Counts Analysis Modal

Press Enter on the Counts section to open a comprehensive analysis modal featuring:

๐Ÿ”ฅ Real-Time Heatmap Visualization

  • Time-series heatmap showing severity levels vs. time (1-minute resolution)
  • 60-minute rolling window with automatic scaling per severity level
  • Color-coded intensity using ASCII characters (โ–‘โ–’โ–“โ–ˆ) with gradient effects
  • Precise alignment with time headers showing minutes ago (60, 50, 40, ..., 10, 0)
  • Receive time architecture - visualization based on when logs were received for reliable display

๐Ÿ” Pattern Analysis by Severity

  • Top 3 patterns per severity using drain3 pattern extraction algorithm
  • Severity-specific tracking with dedicated drain3 instances for each level
  • Real-time pattern detection as logs arrive and are processed
  • Accurate pattern counts maintained separately for each severity level

๐Ÿข Service Distribution Analysis

  • Top 3 services per severity showing which services generate each log level
  • Service name extraction from common attributes (service.name, service, app, etc.)
  • Real-time updates as new logs are processed and analyzed
  • Fallback to host information when service names are not available

โŒจ๏ธ Modal Navigation

  • Scrollable content using mouse wheel or arrow keys
  • ESC to close and return to main dashboard
  • Full-width display maximizing screen real estate for data visualization
  • Real-time updates - data refreshes automatically as new logs arrive

The modal uses the same receive time architecture as the main dashboard, ensuring consistent and reliable visualization regardless of log timestamp accuracy or clock skew issues.

โš™๏ธ Configuration

Command Line Options

gonzo [flags]
gonzo [command]

Commands:
  version     Print version information
  help        Help about any command
  completion  Generate shell autocompletion

Flags:
  -f, --file stringArray           Files or file globs to read logs from (can specify multiple)
  --follow                     Follow log files like 'tail -f' (watch for new lines in real-time)
  -u, --update-interval duration   Dashboard update interval (default: 1s)
  -b, --log-buffer int             Maximum log entries to keep (default: 1000)
  -m, --memory-size int            Maximum frequency entries (default: 10000)
  --ai-model string            AI model for analysis (auto-selects best available if not specified)
  -t, --test-mode                  Run without TTY for testing
  -v, --version                    Print version information
  --config string              Config file (default: $HOME/.config/gonzo/config.yml)
  -h, --help                       Show help message

Configuration File

Create ~/.config/gonzo/config.yml for persistent settings:

# File input configuration
files:
  - "/var/log/app.log"
  - "/var/log/error.log"
  - "/var/log/*.log"  # Glob patterns supported
follow: true  # Enable follow mode (like tail -f)

# Update frequency for dashboard refresh
update-interval: 2s

# Buffer sizes
log-buffer: 2000
memory-size: 15000

# Development/testing
test-mode: false

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

See examples/config.yaml for a complete configuration example with detailed comments.

AI Configuration

Gonzo supports multiple AI providers for intelligent log analysis. Configure using command line flags and environment variables. You can switch between available models at runtime using the m key.

OpenAI

# Set your API key
export OPENAI_API_KEY="sk-your-actual-key-here"

# Auto-select best available model (recommended)
cat logs.json | gonzo

# Or specify a particular model
cat logs.json | gonzo --ai-model="gpt-4"

LM Studio (Local AI)

# 1. Start LM Studio server with a model loaded
# 2. Set environment variables (IMPORTANT: include /v1 in URL)
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"

# Auto-select first available model (recommended)
cat logs.json | gonzo

# Or specify the exact model name from LM Studio
cat logs.json | gonzo --ai-model="openai/gpt-oss-120b"

Ollama (Local AI)

# 1. Start Ollama: ollama serve
# 2. Pull a model: ollama pull gpt-oss:20b
# 3. Set environment variables (note: no /v1 suffix needed)
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"

# Auto-select best model (prefers gpt-oss, llama3, mistral, etc.)
cat logs.json | gonzo

# Or specify a particular model
cat logs.json | gonzo --ai-model="gpt-oss:20b"
cat logs.json | gonzo --ai-model="llama3"

Custom OpenAI-Compatible APIs

# For any OpenAI-compatible API endpoint
export OPENAI_API_KEY="your-api-key"
export OPENAI_API_BASE="https://api.your-provider.com/v1"
cat logs.json | gonzo --ai-model="your-model-name"

Runtime Model Switching

Once Gonzo is running, you can switch between available AI models without restarting:

  1. Press m anywhere in the interface to open the model selection modal
  2. Navigate with arrow keys, page up/down, or mouse wheel
  3. Select a model with Enter
  4. Cancel with Escape

The model selection modal shows:

  • All available models from your configured AI provider
  • Current active model (highlighted in green)
  • Dynamic sizing based on terminal height
  • Scroll indicators when there are many models

Note: Model switching requires the AI service to be properly configured and running. The modal will only appear if models are available from your AI provider.

Auto Model Selection

When you don't specify the --ai-model flag, Gonzo automatically selects the best available model:

Selection Priority:

  1. OpenAI: Prefers gpt-4 โ†’ gpt-3.5-turbo โ†’ first available
  2. Ollama: Prefers gpt-oss:20b โ†’ llama3 โ†’ mistral โ†’ codellama โ†’ first available
  3. LM Studio: Uses first available model from the server
  4. Other providers: Uses first available model

Benefits:

  • โœ… No need to know model names beforehand
  • โœ… Works immediately with any AI provider
  • โœ… Intelligent defaults for better performance
  • โœ… Still allows manual model selection with m key

Example: Instead of gonzo --ai-model="llama3", simply run gonzo and it will auto-select llama3 if available.

Troubleshooting AI Setup

LM Studio Issues:

  • โœ… Ensure server is running and model is loaded
  • โœ… Use full model name: --ai-model="openai/model-name"
  • โœ… Include /v1 in base URL: http://localhost:1234/v1
  • โœ… Check available models: curl http://localhost:1234/v1/models

Ollama Issues:

  • โœ… Start server: ollama serve
  • โœ… Verify model: ollama list
  • โœ… Test API: curl http://localhost:11434/api/tags
  • โœ… Use correct URL: http://localhost:11434 (no /v1 suffix)
  • โœ… Model names include tags: gpt-oss:20b, llama3:8b

OpenAI Issues:

  • โœ… Verify API key is valid and has credits
  • โœ… Check model availability (gpt-4 requires API access)

Environment Variables

Variable Description
OPENAI_API_KEY API key for AI analysis (required for AI features)
OPENAI_API_BASE Custom API endpoint (default: https://api.openai.com/v1)
GONZO_FILES Comma-separated list of files/globs to read (equivalent to -f flags)
GONZO_FOLLOW Enable follow mode (true/false)
GONZO_UPDATE_INTERVAL Override update interval
GONZO_LOG_BUFFER Override log buffer size
GONZO_MEMORY_SIZE Override memory size
GONZO_AI_MODEL Override default AI model
GONZO_TEST_MODE Enable test mode
NO_COLOR Disable colored output

Shell Completion

Enable shell completion for better CLI experience:

# Bash
source <(gonzo completion bash)

# Zsh  
source <(gonzo completion zsh)

# Fish
gonzo completion fish | source

# PowerShell
gonzo completion powershell | Out-String | Invoke-Expression

For permanent setup, save the completion script to your shell's completion directory.

K9s Integration

By leveraging K9s plugin system Gonzo integrates seamlessly with K9s for real-time Kubernetes log analysis.

Setup

Add this plugin to your $XDG_CONFIG_HOME/k9s/plugins.yaml file:

plugins:
  gonzo:
    shortCut: Ctrl-L
    description: "Gonzo log analysis"
    scopes:
    - po
    command: sh
    background: false
    args:
    - -c
    - "kubectl logs -f $NAME -n $NAMESPACE --context $CONTEXT | gonzo"

โš ๏ธ NOTE: on macOS although it is not required, defining XDG_CONFIG_HOME=~/.config is recommended in order to maintain consistency with Linux configuration practices.

Usage

  1. Launch k9s and navigate to pods
  2. Select a pod and press ctrl-l
  3. Gonzo opens with live log streaming and analysis

๐Ÿ—๏ธ Architecture

Gonzo is built with:

  • Bubble Tea - Terminal UI framework
  • Lipgloss - Styling and layout
  • Bubbles - TUI components
  • Cobra - CLI framework
  • Viper - Configuration management
  • OpenTelemetry - Native OTLP support
  • Large amounts of โ˜•๏ธ

The architecture follows a clean separation:

cmd/gonzo/              # Main application entry
internal/
โ”œโ”€โ”€ tui/                # Terminal UI implementation
โ”œโ”€โ”€ analyzer/           # Log analysis engine
โ”œโ”€โ”€ memory/            # Frequency tracking
โ”œโ”€โ”€ otlplog/           # OTLP format handling
โ””โ”€โ”€ ai/                # AI integration

๐Ÿงช Development

Prerequisites

  • Go 1.21 or higher
  • Make (optional, for convenience)

Building

# Quick build
make build

# Run tests
make test

# Build for all platforms
make cross-build

# Development mode (format, vet, test, build)
make dev

Testing

# Run unit tests
make test

# Run with race detection
make test-race

# Integration tests
make test-integration

# Test with sample data
make demo

๐Ÿค Contributing

We love contributions! Please see CONTRIBUTING.md for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

  • Inspired by k9s for the amazing TUI patterns
  • Built with Charm libraries for beautiful terminal UIs
  • OpenTelemetry community for the OTLP specifications

๐Ÿ“š Documentation

๐Ÿ› Reporting Issues

Found a bug? Please open an issue with:

  • Your OS and Go version
  • Steps to reproduce
  • Expected vs actual behavior
  • Log samples (sanitized if needed)

โญ Star History

If you find this project useful, please consider giving it a star! It helps others discover the tool.

Star History Chart


Made with โค๏ธ by ControlTheory and the Gonzo community

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for gonzo

Similar Open Source Tools

For similar tasks

For similar jobs