Skip to content
Back to search

gonzo

Gonzo! The Go based TUI log analysis tool

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/control-theory/gonzo with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/control-theory/gonzo'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/control-theory--gonzo/badge.svg)](/listings/control-theory--gonzo)

HTML

<a href="/listings/control-theory--gonzo"><img src="/api/listings/control-theory--gonzo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/control-theory/gonzo/releases).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "gonzo",
  4. "description": "Gonzo: the open source terminal companion for log analysis and runtime triage. Pipe logs from any source: Vercel, Supabase, K8s, Docker, AWS, Cloudflare, Fly, Render, Railway, Netlify, into a fast TUI with patterns, heatmaps, and anomaly detection. Free. No account required.",
  5. "owner": {
  6. "name": "ControlTheory",
  7. "email": "support@controltheory.com",
  8. "url": "https://controltheory.com"
  9. },
  10. "plugins": [
  11. {
  12. "name": "gonzo",
  13. "source": "./",
  14. "category": "debugging",
  15. "tags": ["log-analysis", "tui", "open-source", "claude-code", "vercel", "supabase", "kubernetes", "docker", "cloudflare"]
  16. }
  17. ]
  18. }
README.md · README · 999 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="https://controltheory.com"><img src="docs/sponsor-controltheory-dstl8.png" alt="Sponsored by ControlTheory: Dstl8"></a>
  3. </p>
  4. # Gonzo - The Go based TUI for log analysis
  5. 🆕 **NEW:** Press `d` from any Gonzo view to launch [Dstl8.Lite](#dstl8-lite) ↓ - a local browser-based dashboard with workspaces, log search, and severity heatmaps.
  6. <p align="center"><img src="docs/gonzo-mascot-smaller.png" width="250" alt="Gonzo Mascot"></p>
  7. [![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-blue)](https://go.dev/)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  9. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
  10. [![Docs](https://img.shields.io/badge/Docs-Getting%20Started-cyan.svg)](https://docs.controltheory.com/)
  11. [![skills.sh](https://img.shields.io/badge/skills.sh-listed-blue)](https://skills.sh/control-theory/gonzo)
  12. A powerful, real-time log analysis terminal UI inspired by k9s. Analyze log streams with beautiful charts, AI-powered insights, and advanced filtering.
  13. Here are some references to get you started:
  14. - **[Documentation](https://docs.controltheory.com/)** - Complete docs, getting started, reference guide
  15. - **[Usage Guide](USAGE_GUIDE.md)** - Detailed usage instructions and examples
  16. - **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
  17. - **[Integration Examples](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples)** - Works with [Vercel](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/vercel-logs), [Supabase](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/supabase-logs), [Railway](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/railway-logs), [Cloudflare Workers](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/cloudflare-logs), [Netlify](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/netlify-logs), [Fly.io](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/fly.io-logs), [Render](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/render-logs), [AWS CloudWatch](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples/aws-cloudwatch-logs), and [more](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/integration-examples).
  18. - **[Advanced Features](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/advanced-features)** - AI, OTel, Custom Log Formats
  19. - **[Releases](https://github.com/control-theory/gonzo/releases)** - Download the latest version
  20. ### See it in action
  21. ![Gonzo Walkthrough](docs/gonzo_video_walkthrough.gif)
  22. ### Main Dashboard
  23. ![Gonzo Main Dashboard](docs/gonzo-main.png)
  24. ### Stats and Info
  25. ![Gonzo Stats](docs/gonzo-stats.png)
  26. ### Everyone loves a heatmap
  27. ![Gonzo Heatmap](docs/gonzo-heatmap.png)
  28. <a id="dstl8-lite"></a>
  29. ### Press `d` for Dstl8.Lite
  30. 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.
  31. <p align="center">
  32. <img src="docs/dstl8-lite-live-logs.gif" alt="Dstl8.Lite Live Logs">
  33. </p>
  34. #### Log viewer with severity filtering and live search
  35. ![Dstl8.Lite Logs](docs/dstl8-lite-logs.png)
  36. #### Severity heatmap across pods
  37. ![Dstl8.Lite Heatmap](docs/dstl8-lite-heatmap-by-pod.png)
  38. ## ✨ Features
  39. ### 🎯 Real-Time Analysis
  40. - **Live streaming** - Process logs as they arrive from stdin, files, or network
  41. - **Kubernetes native** - Direct integration with Kubernetes clusters for pod log streaming
  42. - **OTLP native** - First-class support for OpenTelemetry log format
  43. - **OTLP receiver** - Built-in gRPC server to receive logs via OpenTelemetry protocol
  44. - **Format detection** - Automatically detects JSON, logfmt, and plain text
  45. - **Custom formats** - Define your own log formats with YAML configuration
  46. - **Severity tracking** - Color-coded severity levels with distribution charts
  47. ### 📈 Interactive Dashboard
  48. - **k9s-inspired layout** - Familiar 2x2 grid interface
  49. - **Real-time charts** - Word frequency, attributes, severity distribution, and time series
  50. - **Keyboard + mouse navigation** - Vim-style shortcuts plus click-to-navigate and scroll wheel support
  51. - **Smart log viewer** - Auto-scroll with intelligent pause/resume behavior
  52. - **Fullscreen log viewer** - Press `f` to open a dedicated fullscreen modal for log browsing with all navigation features
  53. - **Global pause control** - Spacebar pauses entire dashboard while buffering logs
  54. - **Modal details** - Deep dive into individual log entries with expandable views
  55. - **Log Counts analysis** - Detailed modal with heatmap visualization, pattern analysis by severity, and service distribution
  56. - **AI analysis** - Get intelligent insights about log patterns and anomalies with configurable models
  57. ### 🌐 Web Dashboard (Dstl8 Lite)
  58. - **Embedded React UI** - Full web dashboard served directly from the Gonzo binary (no external dependencies)
  59. - **Real-time updates** - WebSocket-powered live streaming with 1-second refresh
  60. - **Severity distribution** - Interactive time-series severity charts with stream-level filtering
  61. - **Sentiment heatmap** - Color-coded heatmap visualization grouped by pod, namespace, service, host, or deployment
  62. - **Pattern analysis** - Drain3-powered log pattern detection and classification
  63. - **Log viewer** - Searchable, auto-scrolling log viewer with click-to-expand details
  64. - **Source browser** - Explore log sources with dimension breakdowns
  65. - **Light/dark mode** - Automatic theme support
  66. ### 🔍 Advanced Filtering
  67. - **Regex support** - Filter logs with regular expressions
  68. - **Attribute search** - Find logs by specific attribute values
  69. - **Severity filtering** - Interactive modal to select specific log levels (Ctrl+f)
  70. - **Kubernetes filtering** - Filter by namespace and pod with interactive selection (Ctrl+k)
  71. - **Multi-level selection** - Enable/disable multiple severity levels at once
  72. - **Interactive selection** - Click or keyboard navigate to explore logs
  73. ### 🎨 Customizable Themes
  74. - **Built-in skins** - 11+ beautiful themes including Dracula, Nord, Monokai, GitHub Light, and more
  75. - **Light and dark modes** - Themes optimized for different lighting conditions
  76. - **Custom skins** - Create your own color schemes with YAML configuration
  77. - **Semantic colors** - Intuitive color mapping for different UI components
  78. - **Professional themes** - ControlTheory original themes included
  79. ### 🤖 AI-Powered Insights
  80. - **Pattern detection** - Automatically identify recurring issues
  81. - **Anomaly analysis** - Spot unusual patterns in your logs
  82. - **Root cause suggestions** - Get AI-powered debugging assistance
  83. - **Configurable models** - Choose from GPT-4, GPT-3.5, Claude Sonnet/Haiku/Opus, or any custom model
  84. - **Multiple providers** - Works with OpenAI, Claude Code, LM Studio, Ollama, or any OpenAI-compatible API
  85. - **Local AI support** - Run completely offline with local models
  86. ## 🚀 Quick Start
  87. ### Installation
  88. #### Using Go
  89. ```bash
  90. go install github.com/control-theory/gonzo/cmd/gonzo@latest
  91. ```
  92. #### Using Homebrew (macOS/Linux)
  93. ```bash
  94. brew install gonzo
  95. ```
  96. #### Download Binary
  97. Download the latest release for your platform from the [releases page](https://github.com/control-theory/gonzo/releases).
  98. #### Using Nix package manager (beta support)
  99. ```bash
  100. nix run github:control-theory/gonzo
  101. ```
  102. #### Build from Source
  103. ```bash
  104. git clone https://github.com/control-theory/gonzo.git
  105. cd gonzo
  106. make build
  107. ```
  108. #### Using with Claude Code (plugin and skill)
  109. This repo includes a Claude Code plugin with a guided log-analysis skill. Inside Claude Code:
  110. ```
  111. /plugin marketplace add control-theory/gonzo
  112. /plugin install gonzo@gonzo
  113. ```
  114. 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.
  115. ## 📖 Usage
  116. ### Basic Usage
  117. ```bash
  118. # Read logs directly from files
  119. gonzo -f application.log
  120. # Read from multiple files
  121. gonzo -f application.log -f error.log -f debug.log
  122. # Use glob patterns to read multiple files
  123. gonzo -f "/var/log/*.log"
  124. gonzo -f "/var/log/app/*.log" -f "/var/log/nginx/*.log"
  125. # Follow log files in real-time (like tail -f)
  126. gonzo -f /var/log/app.log --follow
  127. gonzo -f "/var/log/*.log" --follow
  128. # Analyze logs from stdin (traditional way)
  129. cat application.log | gonzo
  130. # Stream logs directly from Kubernetes clusters
  131. gonzo --k8s-enabled=true --k8s-namespaces=default
  132. gonzo --k8s-enabled=true --k8s-namespaces=production --k8s-namespaces=staging
  133. gonzo --k8s-enabled=true --k8s-selector="app=my-app"
  134. # Stream logs from kubectl (traditional way)
  135. kubectl logs -f deployment/my-app | gonzo
  136. # Follow system logs
  137. tail -f /var/log/syslog | gonzo
  138. # Analyze Docker container logs
  139. docker logs -f my-container 2>&1 | gonzo
  140. # With AI analysis (requires API key)
  141. export OPENAI_API_KEY=sk-your-key-here
  142. gonzo -f application.log --ai-model="gpt-4"
  143. # Press `d` once Gonzo is running to launch the Dstl8.Lite GUI in your browser
  144. ```
  145. ### Custom Log Formats
  146. Gonzo supports custom log formats through YAML configuration files. This allows you to parse any structured log format without modifying the source code.
  147. Some example custom formats are included in the repo, simply download, copy, or modify as you like!
  148. In order for the commands below to work, you must first download them and put them in the Gonzo config directory.
  149. ```bash
  150. # Use a built-in custom format
  151. gonzo --format=loki-stream -f loki_logs.json
  152. # List available custom formats
  153. ls ~/.config/gonzo/formats/
  154. # Use your own custom format
  155. gonzo --format=my-custom-format -f custom_logs.txt
  156. ```
  157. Custom formats support:
  158. - **Flexible field mapping** - Map any JSON/text fields to timestamp, severity, body, and attributes
  159. - **Batch processing** - Automatically expand batch formats (like Loki) into individual log entries
  160. - **Auto-mapping** - Automatically extract all unmapped fields as attributes
  161. - **Nested field extraction** - Extract fields from deeply nested JSON structures
  162. - **Pattern-based parsing** - Use regex patterns for unstructured text logs
  163. For detailed information on creating custom formats, see the [Custom Formats Guide](guides/CUSTOM_FORMATS.md).
  164. ### OTLP Network Receiver
  165. Gonzo can receive logs directly via OpenTelemetry Protocol (OTLP) over both gRPC and HTTP:
  166. ```bash
  167. # Start Gonzo as an OTLP receiver (both gRPC on port 4317 and HTTP on port 4318)
  168. gonzo --otlp-enabled
  169. # Use custom ports
  170. gonzo --otlp-enabled --otlp-grpc-port=5317 --otlp-http-port=5318
  171. # gRPC endpoint: localhost:4317
  172. # HTTP endpoint: http://localhost:4318/v1/logs
  173. ```
  174. #### Example: OpenTelemetry Collector Configuration
  175. **Using gRPC:**
  176. ```yaml
  177. exporters:
  178. otlp/gonzo_grpc:
  179. endpoint: localhost:4317
  180. tls:
  181. insecure: true
  182. service:
  183. pipelines:
  184. logs:
  185. receivers: [your_receivers]
  186. processors: [your_processors]
  187. exporters: [otlp/gonzo_grpc]
  188. ```
  189. **Using HTTP:**
  190. ```yaml
  191. exporters:
  192. otlphttp/gonzo_http:
  193. endpoint: http://localhost:4318/v1/logs
  194. service:
  195. pipelines:
  196. logs:
  197. receivers: [your_receivers]
  198. processors: [your_processors]
  199. exporters: [otlphttp/gonzo_http]
  200. ```
  201. #### Example: Python Application
  202. **Using gRPC:**
  203. ```python
  204. from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
  205. exporter = OTLPLogExporter(
  206. endpoint="localhost:4317",
  207. insecure=True
  208. )
  209. ```
  210. **Using HTTP:**
  211. ```python
  212. from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
  213. exporter = OTLPLogExporter(
  214. endpoint="http://localhost:4318/v1/logs",
  215. )
  216. ```
  217. See `examples/send_otlp_logs.py` for a complete example.
  218. ### With AI Analysis
  219. ```bash
  220. # Auto-select best available model (recommended) - file input
  221. export OPENAI_API_KEY=sk-your-key-here
  222. gonzo -f logs.json
  223. # Or specify a particular model - file input
  224. export OPENAI_API_KEY=sk-your-key-here
  225. gonzo -f logs.json --ai-model="gpt-4"
  226. # Follow logs with AI analysis
  227. export OPENAI_API_KEY=sk-your-key-here
  228. gonzo -f "/var/log/app.log" --follow --ai-model="gpt-4"
  229. # Using local LM Studio (auto-selects first available)
  230. export OPENAI_API_KEY="local-key"
  231. export OPENAI_API_BASE="http://localhost:1234/v1"
  232. gonzo -f logs.json
  233. # Using Ollama (auto-selects best model like gpt-oss:20b)
  234. export OPENAI_API_KEY="ollama"
  235. export OPENAI_API_BASE="http://localhost:11434"
  236. gonzo -f logs.json --follow
  237. # Using Claude Code (uses sonnet by default)
  238. gonzo --ai-provider=claude-code -f logs.json
  239. # Claude Code with specific model
  240. gonzo --ai-provider=claude-code --ai-model=haiku -f /var/log/app.log --follow
  241. # Traditional stdin approach still works
  242. export OPENAI_API_KEY=sk-your-key-here
  243. cat logs.json | gonzo --ai-model="gpt-4"
  244. ```
  245. ### Web Dashboard (Dstl8 Lite)
  246. Gonzo includes an embedded web dashboard that runs alongside the TUI. It starts automatically on port 5718.
  247. ```bash
  248. # Gonzo starts the web dashboard automatically
  249. gonzo -f application.log --follow
  250. # Open http://localhost:5718 in your browser
  251. # Use a custom port
  252. gonzo -f application.log --web-port=3000
  253. # Disable the web dashboard
  254. gonzo -f application.log --web-disabled
  255. ```
  256. The dashboard includes:
  257. - **Workspaces** - Overview of all active log streams with sparkline previews
  258. - **Stream Details** - Severity distribution, top attributes, pattern analysis, and live log viewer per stream
  259. - **Sentiment Heatmap** - Real-time heatmap grouped by pod, namespace, service, host, or deployment with auto-detection of available dimensions
  260. - **Sources** - Browse log sources with dimension breakdowns
  261. All data updates in real-time via WebSocket, matching what you see in the TUI.
  262. ### Keyboard Shortcuts
  263. #### Navigation
  264. | Key/Mouse | Action |
  265. | ------------------- | -------------------------------------------------------- |
  266. | `Tab` / `Shift+Tab` | Navigate between panels |
  267. | `Mouse Click` | Click on any section to switch to it |
  268. | `↑`/`↓` or `k`/`j` | Move selection up/down |
  269. | `Mouse Wheel` | Scroll up/down to navigate selections |
  270. | `←`/`→` or `h`/`l` | Horizontal navigation |
  271. | `Enter` | View log details or open analysis modal (Counts section) |
  272. | `ESC` | Close modal/cancel |
  273. #### Actions
  274. | Key | Action |
  275. | -------------- | ----------------------------------------- |
  276. | `Space` | Pause/unpause entire dashboard |
  277. | `/` | Enter filter mode (regex supported) |
  278. | `s` | Search and highlight text in logs |
  279. | `d` | Launch Dstl8.Lite GUI in browser |
  280. | `Ctrl+f` | Open severity filter modal |
  281. | `Ctrl+k` | Open Kubernetes filter modal (k8s mode) |
  282. | `f` | Open fullscreen log viewer modal |
  283. | `c` | Toggle columns (Host/Service ↔ Namespace/Pod in k8s mode) |
  284. | `C` | Configure visible columns (column picker) |
  285. | `r` | Reset all data (manual reset) |
  286. | `u` / `U` | Cycle update intervals (forward/backward) |
  287. | `i` | AI analysis (in detail view) |
  288. | `m` | Switch AI model (shows available models) |
  289. | `?` / `h` | Show help |
  290. | `q` / `Ctrl+C` | Quit |
  291. #### Log Viewer Navigation
  292. | Key | Action |
  293. | ------------------ | --------------------------------------------- |
  294. | `Home` | Jump to top of log buffer (stops auto-scroll) |
  295. | `End` | Jump to latest logs (resumes auto-scroll) |
  296. | `PgUp` / `PgDn` | Navigate by pages (10 entries at a time) |
  297. | `↑`/`↓` or `k`/`j` | Navigate entries with smart auto-scroll |
  298. #### AI Chat (in log detail modal)
  299. | Key | Action |
  300. | ----- | ---------------------------------------- |
  301. | `c` | Start chat with AI about current log |
  302. | `Tab` | Switch between log details and chat pane |
  303. | `m` | Switch AI model (works in modal too) |
  304. #### Severity Filter Modal
  305. The severity filter modal (`Ctrl+f`) provides fine-grained control over which log levels to display:
  306. | Key | Action |
  307. | ------------------ | ------------------------------------------------- |
  308. | `↑`/`↓` or `k`/`j` | Navigate severity options |
  309. | `Space` | Toggle selected severity level on/off |
  310. | `Enter` | Apply filter and close modal (or select All/None) |
  311. | `ESC` | Cancel changes and close modal |
  312. **Features:**
  313. - **Select All** - Quick option to enable all severity levels (Enter to apply and close)
  314. - **Select None** - Quick option to disable all severity levels (Enter to apply and close)
  315. - **Individual toggles** - Enable/disable specific levels (FATAL, ERROR, WARN, INFO, DEBUG, TRACE, etc.)
  316. - **Color-coded display** - Each severity level shows in its standard color
  317. - **Real-time count** - Header shows how many levels are currently active
  318. - **Persistent filtering** - Applied filters remain active until changed
  319. - **Quick shortcuts** - Press Enter on Select All/None to apply immediately
  320. #### Column Picker Modal
  321. The column picker modal (`C` key) lets you configure which columns are visible in the log viewer:
  322. | Key | Action |
  323. | ------------------ | ----------------------------------- |
  324. | `↑`/`↓` or `k`/`j` | Navigate column options |
  325. | `Space` | Toggle selected column on/off |
  326. | `Enter` | Apply changes and close modal |
  327. | `ESC` | Discard changes and close modal |
  328. **Features:**
  329. - **Default Columns** - Built-in columns like Timestamp, Severity, Host, Service, and Message
  330. - **Discovered Attributes** - Dynamically detected attribute keys from incoming log data
  331. - **Active counter** - Header shows `(N/M active)` indicating how many columns are currently enabled
  332. ### Log Counts Analysis Modal
  333. Press `Enter` on the Counts section to open a comprehensive analysis modal featuring:
  334. #### 🔥 Real-Time Heatmap Visualization
  335. - **Time-series heatmap** showing severity levels vs. time (1-minute resolution)
  336. - **60-minute rolling window** with automatic scaling per severity level
  337. - **Color-coded intensity** using ASCII characters (░▒▓█) with gradient effects
  338. - **Precise alignment** with time headers showing minutes ago (60, 50, 40, ..., 10, 0)
  339. - **Receive time architecture** - visualization based on when logs were received for reliable display
  340. #### 🔍 Pattern Analysis by Severity
  341. - **Top 3 patterns per severity** using drain3 pattern extraction algorithm
  342. - **Severity-specific tracking** with dedicated drain3 instances for each level
  343. - **Real-time pattern detection** as logs arrive and are processed
  344. - **Accurate pattern counts** maintained separately for each severity level
  345. #### 🏢 Service Distribution Analysis
  346. - **Top 3 services per severity** showing which services generate each log level
  347. - **Service name extraction** from common attributes (service.name, service, app, etc.)
  348. - **Real-time updates** as new logs are processed and analyzed
  349. - **Fallback to host information** when service names are not available
  350. #### ⌨️ Modal Navigation
  351. - **Scrollable content** using mouse wheel or arrow keys
  352. - **ESC to close** and return to main dashboard
  353. - **Full-width display** maximizing screen real estate for data visualization
  354. - **Real-time updates** - data refreshes automatically as new logs arrive
  355. 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.
  356. ## ⚙️ Configuration
  357. ### Command Line Options
  358. ```bash
  359. gonzo [flags]
  360. gonzo [command]
  361. Commands:
  362. version Print version information
  363. help Help about any command
  364. completion Generate shell autocompletion
  365. Flags:
  366. -f, --file stringArray Files or file globs to read logs from (can specify multiple)
  367. --follow Follow log files like 'tail -f' (watch for new lines in real-time)
  368. --format string Log format to use (auto-detect if not specified). Can be: otlp, json, text, or a custom format name
  369. -u, --update-interval duration Dashboard update interval (default: 1s)
  370. -b, --log-buffer int Maximum log entries to keep (default: 1000)
  371. -m, --memory-size int Maximum frequency entries (default: 10000)
  372. --ai-provider string AI provider to use: 'openai' (default), 'claude-code'
  373. --ai-model string AI model for analysis (auto-selects best available if not specified)
  374. -s, --skin string Color scheme/skin to use (default, or name of a skin file)
  375. --stop-words strings Additional stop words to filter out from analysis (adds to built-in list)
  376. Web Dashboard Flags:
  377. --web-port int Port for the Dstl8 Lite web dashboard (default: 5718)
  378. --web-disabled Disable the web dashboard
  379. Kubernetes Flags:
  380. --k8s-enabled=true Enable Kubernetes log streaming mode
  381. --k8s-namespaces stringArray Kubernetes namespace(s) to watch (can specify multiple, default: all)
  382. --k8s-selector string Kubernetes label selector for filtering pods
  383. --k8s-tail int Number of previous log lines to retrieve (default: 10)
  384. --k8s-since int Only return logs newer than relative duration in seconds
  385. --k8s-kubeconfig string Path to kubeconfig file (default: $KUBECONFIG or $HOME/.kube/config)
  386. --k8s-context string Kubernetes context to use
  387. -t, --test-mode Run without TTY for testing
  388. -v, --version Print version information
  389. --config string Config file (default: $HOME/.config/gonzo/config.yml)
  390. -h, --help Show help message
  391. ```
  392. ### Configuration File
  393. Create `~/.config/gonzo/config.yml` for persistent settings:
  394. ```yaml
  395. # File input configuration
  396. files:
  397. - "/var/log/app.log"
  398. - "/var/log/error.log"
  399. - "/var/log/*.log" # Glob patterns supported
  400. follow: true # Enable follow mode (like tail -f)
  401. # Update frequency for dashboard refresh
  402. update-interval: 2s
  403. # Buffer sizes
  404. log-buffer: 2000
  405. memory-size: 15000
  406. # UI customization
  407. skin: dracula # Choose from: default, dracula, nord, monokai, github-light, etc.
  408. # Additional stop words to filter from analysis
  409. stop-words:
  410. - "log"
  411. - "message"
  412. - "debug"
  413. # Development/testing
  414. test-mode: false
  415. # AI configuration
  416. ai-provider: "openai" # Options: "openai" (default), "claude-code"
  417. ai-model: "gpt-4"
  418. # Web dashboard (Dstl8 Lite)
  419. web-port: 5718 # Port for the web dashboard
  420. web-disabled: false # Set to true to disable
  421. ```
  422. See [examples/config.yml](examples/config.yml) for a complete configuration example with detailed comments.
  423. ### AI Configuration
  424. 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.
  425. #### OpenAI
  426. ```bash
  427. # Set your API key
  428. export OPENAI_API_KEY="sk-your-actual-key-here"
  429. # Auto-select best available model (recommended)
  430. cat logs.json | gonzo
  431. # Or specify a particular model
  432. cat logs.json | gonzo --ai-model="gpt-4"
  433. ```
  434. #### Claude Code (Anthropic Claude)
  435. ```bash
  436. # 1. Install Claude Code CLI
  437. # Download from https://claude.ai/download
  438. # 2. Authenticate (if not already done)
  439. claude auth login
  440. # 3. Run Gonzo with Claude Code (uses sonnet by default)
  441. gonzo --ai-provider=claude-code -f application.log
  442. # Specify a model
  443. gonzo --ai-provider=claude-code --ai-model=sonnet -f logs.json # Default, balanced
  444. gonzo --ai-provider=claude-code --ai-model=haiku -f logs.json # Faster, efficient
  445. gonzo --ai-provider=claude-code --ai-model=opus -f logs.json # Most capable
  446. # Works with all input methods
  447. gonzo --ai-provider=claude-code --k8s-enabled
  448. cat logs.json | gonzo --ai-provider=claude-code
  449. tail -f /var/log/app.log | gonzo --ai-provider=claude-code --ai-model=haiku
  450. # Run Claude in a container (Podman/Docker)
  451. export GONZO_CLAUDE_PATH="podman exec -it claude-container claude"
  452. gonzo --ai-provider=claude-code -f logs.json
  453. export GONZO_CLAUDE_PATH="docker exec -it my-claude-container claude"
  454. gonzo --ai-provider=claude-code --ai-model=haiku -f /var/log/app.log --follow
  455. ```
  456. **Available Models:**
  457. - `sonnet` (default) - Claude Sonnet, balanced performance and capability
  458. - `haiku` - Fastest and most efficient, best for high-volume logs
  459. - `opus` - Most capable, best for complex analysis
  460. **Notes:**
  461. - Claude Code CLI manages authentication independently. The `OPENAI_API_KEY` environment variable is not needed.
  462. - Use `GONZO_CLAUDE_PATH` to specify a custom path or command (useful for running Claude in containers).
  463. #### LM Studio (Local AI)
  464. ```bash
  465. # 1. Start LM Studio server with a model loaded
  466. # 2. Set environment variables (IMPORTANT: include /v1 in URL)
  467. export OPENAI_API_KEY="local-key"
  468. export OPENAI_API_BASE="http://localhost:1234/v1"
  469. # Auto-select first available model (recommended)
  470. cat logs.json | gonzo
  471. # Or specify the exact model name from LM Studio
  472. cat logs.json | gonzo --ai-model="openai/gpt-oss-120b"
  473. ```
  474. #### Ollama (Local AI)
  475. ```bash
  476. # 1. Start Ollama: ollama serve
  477. # 2. Pull a model: ollama pull gpt-oss:20b
  478. # 3. Set environment variables (note: no /v1 suffix needed)
  479. export OPENAI_API_KEY="ollama"
  480. export OPENAI_API_BASE="http://localhost:11434"
  481. # Auto-select best model (prefers gpt-oss, llama3, mistral, etc.)
  482. cat logs.json | gonzo
  483. # Or specify a particular model
  484. cat logs.json | gonzo --ai-model="gpt-oss:20b"
  485. cat logs.json | gonzo --ai-model="llama3"
  486. ```
  487. #### Custom OpenAI-Compatible APIs
  488. ```bash
  489. # For any OpenAI-compatible API endpoint
  490. export OPENAI_API_KEY="your-api-key"
  491. export OPENAI_API_BASE="https://api.your-provider.com/v1"
  492. cat logs.json | gonzo --ai-model="your-model-name"
  493. ```
  494. #### Runtime Model Switching
  495. Once Gonzo is running, you can switch between available AI models without restarting:
  496. 1. **Press `m`** anywhere in the interface to open the model selection modal
  497. 2. **Navigate** with arrow keys, page up/down, or mouse wheel
  498. 3. **Select** a model with Enter
  499. 4. **Cancel** with Escape
  500. The model selection modal shows:
  501. - All available models from your configured AI provider
  502. - Current active model (highlighted in green)
  503. - Dynamic sizing based on terminal height
  504. - Scroll indicators when there are many models
  505. **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.
  506. **Provider-Specific Behavior:**
  507. - **OpenAI/Ollama/LM Studio**: Shows all models available from the API
  508. - **Claude Code**: Shows sonnet, haiku, and opus (managed by Claude CLI)
  509. #### Auto Model Selection
  510. When you don't specify the `--ai-model` flag, Gonzo automatically selects the best available model:
  511. **Selection Priority:**
  512. 1. **OpenAI**: Prefers `gpt-4` → `gpt-3.5-turbo` → first available
  513. 2. **Claude Code**: Defaults to `sonnet` (haiku and opus also available)
  514. 3. **Ollama**: Prefers `gpt-oss:20b` → `llama3` → `mistral` → `codellama` → first available
  515. 4. **LM Studio**: Uses first available model from the server
  516. 5. **Other providers**: Uses first available model
  517. **Benefits:**
  518. - ✅ No need to know model names beforehand
  519. - ✅ Works immediately with any AI provider
  520. - ✅ Intelligent defaults for better performance
  521. - ✅ Still allows manual model selection with `m` key
  522. **Example:** Instead of `gonzo --ai-model="llama3"`, simply run `gonzo` and it will auto-select `llama3` if available.
  523. #### Troubleshooting AI Setup
  524. **LM Studio Issues:**
  525. - ✅ Ensure server is running and model is loaded
  526. - ✅ Use full model name: `--ai-model="openai/model-name"`
  527. - ✅ Include `/v1` in base URL: `http://localhost:1234/v1`
  528. - ✅ Check available models: `curl http://localhost:1234/v1/models`
  529. **Ollama Issues:**
  530. - ✅ Start server: `ollama serve`
  531. - ✅ Verify model: `ollama list`
  532. - ✅ Test API: `curl http://localhost:11434/api/tags`
  533. - ✅ Use correct URL: `http://localhost:11434` (no `/v1` suffix)
  534. - ✅ Model names include tags: `gpt-oss:20b`, `llama3:8b`
  535. **OpenAI Issues:**
  536. - ✅ Verify API key is valid and has credits
  537. - ✅ Check model availability (gpt-4 requires API access)
  538. **Claude Code Issues:**
  539. - ✅ Ensure Claude Code CLI is installed: `claude --version`
  540. - ✅ Authenticate with Claude: `claude auth login`
  541. - ✅ Test CLI access: `claude -p "test prompt"`
  542. - ✅ Available models: `sonnet` (default), `haiku`, `opus`
  543. - ✅ Use `--ai-provider=claude-code` flag when running Gonzo
  544. ### Environment Variables
  545. | Variable | Description |
  546. | ----------------------- | -------------------------------------------------------------------- |
  547. | `OPENAI_API_KEY` | API key for AI analysis (required for OpenAI-based AI features) |
  548. | `OPENAI_API_BASE` | Custom API endpoint (default: <https://api.openai.com/v1>) |
  549. | `GONZO_AI_PROVIDER` | AI provider to use ('openai' or 'claude-code') |
  550. | `GONZO_CLAUDE_PATH` | Custom path/command for Claude CLI (e.g., for container execution) |
  551. | `GONZO_FILES` | Comma-separated list of files/globs to read (equivalent to -f flags) |
  552. | `GONZO_FOLLOW` | Enable follow mode (true/false) |
  553. | `GONZO_UPDATE_INTERVAL` | Override update interval |
  554. | `GONZO_LOG_BUFFER` | Override log buffer size |
  555. | `GONZO_MEMORY_SIZE` | Override memory size |
  556. | `GONZO_AI_MODEL` | Override default AI model |
  557. | `GONZO_WEB_PORT` | Override web dashboard port (default: 5718) |
  558. | `GONZO_WEB_DISABLED` | Disable web dashboard (true/false) |
  559. | `GONZO_TEST_MODE` | Enable test mode |
  560. | `NO_COLOR` | Disable colored output |
  561. ### Shell Completion
  562. Enable shell completion for better CLI experience:
  563. ```bash
  564. # Bash
  565. source <(gonzo completion bash)
  566. # Zsh
  567. source <(gonzo completion zsh)
  568. # Fish
  569. gonzo completion fish | source
  570. # PowerShell
  571. gonzo completion powershell | Out-String | Invoke-Expression
  572. ```
  573. For permanent setup, save the completion script to your shell's completion directory.
  574. ### K9s Integration
  575. By leveraging [K9s plugin system](https://k9scli.io/topics/plugins/) Gonzo integrates seamlessly with K9s for real-time Kubernetes log analysis.
  576. #### Setup
  577. Add this plugin to your `$XDG_CONFIG_HOME/k9s/plugins.yaml` file:
  578. ```yaml
  579. plugins:
  580. gonzo:
  581. shortCut: Ctrl-L
  582. description: "Gonzo log analysis"
  583. scopes:
  584. - po
  585. - deploy
  586. - sts
  587. - ds
  588. - svc
  589. - job
  590. - cj
  591. command: sh
  592. background: false
  593. args:
  594. - -c
  595. - "kubectl logs -f --tail=0 $RESOURCE_NAME/$NAME -n $NAMESPACE --context $CONTEXT | gonzo"
  596. ```
  597. > ⚠️ NOTE: on `macOS` although it is not required, defining `XDG_CONFIG_HOME=~/.config` is recommended in order to maintain consistency with Linux configuration practices.
  598. #### Usage
  599. 1. Launch k9s and navigate to pods
  600. 2. Select a pod and press `ctrl-l`
  601. 3. Gonzo opens with live log streaming and analysis
  602. ## 🏗️ Architecture
  603. Gonzo is built with:
  604. - **[Bubble Tea](https://github.com/charmbracelet/bubbletea)** - Terminal UI framework
  605. - **[Lipgloss](https://github.com/charmbracelet/lipgloss)** - Styling and layout
  606. - **[Bubbles](https://github.com/charmbracelet/bubbles)** - TUI components
  607. - **[Cobra](https://github.com/spf13/cobra)** - CLI framework
  608. - **[Viper](https://github.com/spf13/viper)** - Configuration management
  609. - **OpenTelemetry** - Native OTLP support
  610. - **Large amounts of** ☕️
  611. The architecture follows a clean separation with a shared analysis engine:
  612. ```
  613. cmd/gonzo/ # Main application entry
  614. internal/
  615. ├── engine/ # Shared analysis engine (feeds TUI and web)
  616. ├── tui/ # Terminal UI implementation
  617. ├── web/ # Dstl8 Lite web dashboard (embedded React)
  618. ├── analyzer/ # Log analysis engine
  619. ├── memory/ # Frequency tracking
  620. ├── otlplog/ # OTLP format handling
  621. └── ai/ # AI integration
  622. web/ # React frontend source (Vite + TypeScript)
  623. ```
  624. ## 🧪 Development
  625. ### Prerequisites
  626. - Go 1.25 or higher
  627. - Make (optional, for convenience)
  628. ### Building
  629. ```bash
  630. # Quick build (includes web dashboard)
  631. make build
  632. # Build web dashboard only
  633. make web-deps # Install npm dependencies
  634. make web-build # Build React app
  635. # Run tests
  636. make test
  637. # Build for all platforms
  638. make cross-build
  639. # Development mode (format, vet, test, build)
  640. make dev
  641. ```
  642. ### Testing
  643. ```bash
  644. # Run unit tests
  645. make test
  646. # Run with race detection
  647. make test-race
  648. # Integration tests
  649. make test-integration
  650. # Test with sample data
  651. make demo
  652. ```
  653. ## 🎨 Customization & Themes
  654. Gonzo supports beautiful, customizable color schemes to match your terminal environment and personal preferences.
  655. ### Using Built-in Themes
  656. Be sure you download and place in the Gonzo config directory so Gonzo can find them.
  657. ```bash
  658. # Use a dark theme
  659. gonzo --skin=dracula
  660. gonzo --skin=nord
  661. gonzo --skin=monokai
  662. # Use a light theme
  663. gonzo --skin=github-light
  664. gonzo --skin=solarized-light
  665. gonzo --skin=vs-code-light
  666. # Use Control Theory branded themes
  667. gonzo --skin=controltheory-light # Light theme
  668. gonzo --skin=controltheory-dark # Dark theme
  669. ```
  670. ### Available Themes
  671. **Dark Themes 🌙**: `default`, `controltheory-dark`, `dracula`, `gruvbox`, `monokai`, `nord`, `solarized-dark`
  672. **Light Themes ☀️**: `controltheory-light`, `github-light`, `solarized-light`, `vs-code-light`, `spring`
  673. ### Creating Custom Themes
  674. See **[SKINS.md](guides/SKINS.md)** for complete documentation on:
  675. - 📖 How to create custom color schemes
  676. - 🎯 Color reference and semantic naming
  677. - 📦 Downloading community themes from GitHub
  678. - 🔧 Advanced customization options
  679. - 🎨 Design guidelines for accessibility
  680. ## 🤝 Contributing
  681. We love contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
  682. 1. Fork the repository
  683. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  684. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  685. 4. Push to the branch (`git push origin feature/amazing-feature`)
  686. 5. Open a Pull Request
  687. ## 📝 License
  688. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  689. ## 🙏 Acknowledgments
  690. - Inspired by [k9s](https://k9scli.io/) for the amazing TUI patterns
  691. - Built with [Charm](https://charm.sh/) libraries for beautiful terminal UIs
  692. - OpenTelemetry community for the OTLP specifications
  693. ## 📚 Documentation
  694. - [Docs](https://docs.controltheory.com/) - Complete user guide, integration examples, advanced features (AI, OTel, custom log formats)
  695. - [Usage Guide](USAGE_GUIDE.md) - Detailed usage instructions
  696. - [Kubernetes Integration Guide](guides/KUBERNETES_USAGE.md) - Direct Kubernetes cluster integration, filtering, and usage examples
  697. - [AWS CloudWatch Logs Usage Guide](guides/CLOUDWATCH_USAGE_GUIDE.md) - Usage instructions for AWS CLI log tail and live tail with Gonzo
  698. - [Stern Usage Guide](guides/STERN_USAGE_GUIDE.md) - Usage and examples for using Stern with Gonzo
  699. - [Victoria Logs Integration](guides/VICTORIA_LOGS_USAGE.md) - Using Gonzo with Victoria Logs API
  700. - [Web Dashboard](guides/WEB_DASHBOARD_USAGE.md) - Dstl8 Lite web UI setup
  701. - [Contributing Guide](CONTRIBUTING.md) - How to contribute
  702. - [Changelog](CHANGELOG.md) - Version history
  703. ## 🎥 Talks & Demos
  704. * **[Gonzo Roadmap & Pro Tips Live Demo with Maintainers](https://www.controltheory.com/videos/gonzo-roadmap-and-pro-tips-live-demo-session/)** - Live session covering the roadmap, advanced features, and Q&A with the maintainers
  705. ## 💬 Community
  706. - [Discord](https://discord.gg/nRBUFYByta)
  707. - [Slack Invite/Join](https://join.slack.com/t/ctrltheorycommunity/shared_invite/zt-3dr6rke5w-GlcRaW2bvn4zcSaV8byZgA)
  708. - [Slack Channel Link](https://ctrltheorycommunity.slack.com)
  709. ## 🐛 Reporting Issues
  710. Found a bug? Please [open an issue](https://github.com/control-theory/gonzo/issues/new) with:
  711. - Your OS and Go version
  712. - Steps to reproduce
  713. - Expected vs actual behavior
  714. - Log samples (sanitized if needed)
  715. ## ⭐ Star History
  716. If you find this project useful, please consider giving it a star! It helps others discover the tool.
  717. [![Star History Chart](https://api.star-history.com/svg?repos=control-theory/gonzo&type=Date)](https://www.star-history.com/#control-theory/gonzo&Date)
  718. ---
  719. <p align="center">
  720. Made with ❤️ by <a href="https://controltheory.com">ControlTheory</a> and the Gonzo community
  721. </p>
  722. <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=acef447d-5cc3-4756-a46a-8c384b9babf2&page=README.md" width="1" height="1" />

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.