Gonzo - The Go based TUI for log analysis

🆕 NEW: Press d from any Gonzo view to launch Dstl8.Lite ↓ - a local browser-based dashboard with workspaces, log search, and severity heatmaps.

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

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

Main Dashboard

Stats and Info

Everyone loves a heatmap

Press d for Dstl8.Lite

Hit d from any Gonzo view to launch Dstl8.Lite - a local GUI that streams the same logs Gonzo is analyzing into a richer, browser-based dashboard with workspaces, pattern detection, severity heatmaps, and live log search. All running locally and powered by Gonzo under the hood.

Log viewer with severity filtering and live search

Severity heatmap across pods

✨ 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

🌐 Web Dashboard (Dstl8 Lite)

• Embedded React UI - Full web dashboard served directly from the Gonzo binary (no external dependencies)
• Real-time updates - WebSocket-powered live streaming with 1-second refresh
• Severity distribution - Interactive time-series severity charts with stream-level filtering
• Sentiment heatmap - Color-coded heatmap visualization grouped by pod, namespace, service, host, or deployment
• Pattern analysis - Drain3-powered log pattern detection and classification
• Log viewer - Searchable, auto-scrolling log viewer with click-to-expand details
• Source browser - Explore log sources with dimension breakdowns
• Light/dark mode - Automatic theme support

🔍 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

Using with Claude Code (plugin and skill)

This repo includes a Claude Code plugin with a guided log-analysis skill. Inside Claude Code:

/plugin marketplace add control-theory/gonzo
/plugin install gonzo@gonzo

Then ask Claude to "tail my logs", "watch my Vercel logs", or "analyze my Kubernetes logs". The skill detects your deployment platform, installs Gonzo if needed, configures AI analysis, and generates the right pipe command with platform-specific normalizers. See skills/gonzo/ for the skill content.

📖 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"

# Press `d` once Gonzo is running to launch the Dstl8.Lite GUI in your browser

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

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

# Using Claude Code (uses sonnet by default)
gonzo --ai-provider=claude-code -f logs.json

# Claude Code with specific model
gonzo --ai-provider=claude-code --ai-model=haiku -f /var/log/app.log --follow

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

Web Dashboard (Dstl8 Lite)

Gonzo includes an embedded web dashboard that runs alongside the TUI. It starts automatically on port 5718.

# Gonzo starts the web dashboard automatically
gonzo -f application.log --follow
# Open http://localhost:5718 in your browser

# Use a custom port
gonzo -f application.log --web-port=3000

# Disable the web dashboard
gonzo -f application.log --web-disabled

The dashboard includes: - Workspaces - Overview of all active log streams with sparkline previews - Stream Details - Severity distribution, top attributes, pattern analysis, and live log viewer per stream - Sentiment Heatmap - Real-time heatmap grouped by pod, namespace, service, host, or deployment with auto-dete