Gonzo - The Go based TUI for log analysis

📢 LIVE SESSION RECORDING NOW AVAILABLE:
Gonzo Roadmap & Pro Tips Live Demo with Maintainers
Watch here

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.

Here are some references to get you started:

Documentation - Complete docs, getting started, reference guide
Usage Guide - Detailed usage instructions and examples
Contributing Guide - How to contribute to the project
Integration Examples - Works with Vercel, Supabase, Railway, Cloudflare Workers, Netlify, Fly.io, Render, AWS CloudWatch, and more.
Advanced Features - AI, OTel, Custom Log Formats
Releases - Download the latest version

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
Kubernetes native - Direct integration with Kubernetes clusters for pod log streaming
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
Custom formats - Define your own log formats with YAML configuration
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 - Interactive modal to select specific log levels (Ctrl+f)
Kubernetes filtering - Filter by namespace and pod with interactive selection (Ctrl+k)
Multi-level selection - Enable/disable multiple severity levels at once
Interactive selection - Click or keyboard navigate to explore logs

🎨 Customizable Themes

Built-in skins - 11+ beautiful themes including Dracula, Nord, Monokai, GitHub Light, and more
Light and dark modes - Themes optimized for different lighting conditions
Custom skins - Create your own color schemes with YAML configuration
Semantic colors - Intuitive color mapping for different UI components
Professional themes - ControlTheory original themes included

🤖 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, Claude Sonnet/Haiku/Opus, or any custom model
Multiple providers - Works with OpenAI, Claude Code, 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 directly from Kubernetes clusters
gonzo --k8s-enabled=true --k8s-namespaces=default
gonzo --k8s-enabled=true --k8s-namespaces=production --k8s-namespaces=staging
gonzo --k8s-enabled=true --k8s-selector="app=my-app"

# Stream logs from kubectl (traditional way)
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"

Custom Log Formats

Gonzo supports custom log formats through YAML configuration files. This allows you to parse any structured log format without modifying the source code.

Some example custom formats are included in the repo, simply download, copy, or modify as you like! In order for the commands below to work, you must first download them and put them in the Gonzo config directory.

# Use a built-in custom format
gonzo --format=loki-stream -f loki_logs.json

# List available custom formats
ls ~/.config/gonzo/formats/

# Use your own custom format
gonzo --format=my-custom-format -f custom_logs.txt

Custom formats support:

Flexible field mapping - Map any JSON/text fields to timestamp, severity, body, and attributes
Batch processing - Automatically expand batch formats (like Loki) into individual log entries
Auto-mapping - Automatically extract all unmapped fields as attributes
Nested field extraction - Extract fields from deeply nested JSON structures
Pattern-based parsing - Use regex patterns for unstructured text logs

For detailed information on creating custom formats, see the Custom Formats Guide.

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