共计 3892 个字符，预计需要花费 10 分钟才能阅读完成。
下面是一份面向实战的 ） 项目介绍 + 详尽上手教程。内容涵盖特性、安装、常见来源接入（文件 /kubectl/Docker/OTLP/VictoriaLogs）、AI 助力分析、K9s 集成、主题 / 快捷键与最佳实践。
注：Gonzo 是一个受 k9s 启发的开源 TUI 日志分析器，支持实时图表、正则过滤、严重级别筛选、可配置 AI 模型，以及原生 OTLP（OpenTelemetry）接入。本文命令与参数均以官方 README/Usage Guide/Release 为准。(gonzo.controltheory.com)
一、项目简介（做什么 / 适用场景）
- 定位：在终端里用“仪表盘式”界面实时分析日志，带有词频 / 时间序列 / 严重性分布等图表，并可一键深入某条日志详情。适合开发、运维、SRE 的日常排障与观察性分析。(gonzo.controltheory.com)
- 数据源：文件 / 标准输入、
kubectl logs、Docker 输出、系统日志；原生 OTLP（gRPC/HTTP）收取，亦支持 Victoria Logs。(GitHub) - AI 助力：可选择 OpenAI、Ollama、LM Studio 等（也可离线），执行模式识别、异常分析与“可能根因”建议；运行时可热切换模型。(GitHub)
- 可定制：YAML 自定义日志格式（如 Loki 批量格式）、皮肤主题与快捷键提示等。(GitHub)
- 开源协议：MIT。近期版本增加主题、严重级别过滤、Victoria Logs 支持等。(GitHub)
二、安装（任选其一）
# 1) Go 安装（需 Go 1.21+）go install github.com/control-theory/gonzo/cmd/gonzo@latest
# 2) Homebrew（macOS/Linux）brew install gonzo
# 3) 直接下载二进制（releases 页面）# 4) 源码构建
git clone https://github.com/control-theory/gonzo.git
cd gonzo && make build
以上命令来自官方 Quick Start。(GitHub)
三、5 分钟快速上手
最小示例
# 文件 / 多文件 / 通配符
gonzo -f application.log
gonzo -f "/var/log/*.log" --follow # 类似 tail -f
# 传统管道
cat application.log | gonzo
# Kubernetes
kubectl logs -f deployment/my-app | gonzo
# Docker
docker logs -f my-container 2>&1 | gonzo
常用入门命令与参数如上。(GitHub)
四、把 AI 接入到日志分析（本地 / 云都行）
# OpenAI（示例）export OPENAI_API_KEY=sk-... # 然后直接运行
gonzo -f logs.json
# 或显式选择模型
gonzo -f logs.json --ai-model="gpt-4"
# LM Studio（本地）export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"
gonzo -f logs.json
# Ollama（本地）export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
gonzo -f logs.json --follow
# 运行中热切换模型：按 m 打开模型选择面板
支持自动选型与运行中切换；也可通过环境变量覆盖默认配置。(GitHub)
五、接入更多日志来源
1) 作为 OTLP 接收端
# 同时开启 gRPC:4317 / HTTP:4318
gonzo --otlp-enabled
# 自定义端口
gonzo --otlp-enabled --otlp-grpc-port=5317 --otlp-http-port=5318
OpenTelemetry Collector（示例）：
# gRPC
exporters:
otlp/gonzo_grpc:
endpoint: localhost:4317
tls: {insecure: true}
service:
pipelines:
logs:
receivers: [your_receivers]
processors: [your_processors]
exporters: [otlp/gonzo_grpc]
HTTP 的配置同理；仓库还附带 Python OTLP 日志发送示例。(GitHub)
2) Victoria Logs（时序日志存储）
- 可通过命令行参数连接 VictoriaLogs 并查询；官方文档含专门集成指南。(gonzo.controltheory.com)
3) AWS CloudWatch / Stern 等
- 仓库提供 CloudWatch & Stern 使用指南，结合原生命令实时拉流到 Gonzo。(GitHub)
六、像专业人士那样“读懂”日志
A. 交互面板与快捷键（摘选）
- 面板切换：
Tab / Shift+Tab、鼠标点击 - 滚动 / 导航：
↑/↓/PgUp/PgDn、鼠标滚轮 - 过滤：
/进入过滤模式（支持 正则）；Ctrl+f打开严重级别筛选 - 暂停缓冲：
Space（后台继续缓冲） - 详情 / 分析：
Enter打开详情或“Counts”分析模态；i让 AI 对当前日志给出洞察 - 帮助：
?/h；退出：q/Ctrl+C
更多按键与“日志计数分析”（热力图 / 模式提取 / 服务分布）详见 Usage Guide。(GitHub)
B. 高级过滤与属性检索
- 支持正则、属性搜索、严重级别多选；交互式选择配合点击 / 键盘快速钻取。(GitHub)
七、定制“可读性”：主题 & 皮肤
# 内置主题（示例）gonzo --skin=dracula
gonzo --skin=nord
gonzo --skin=github-light
也可创建自定义皮肤（YAML），或选择 ControlTheory 官方主题。(GitHub)
八、K9s 插件集成（一键从 Pod 打开 Gonzo）
在 ~/.config/k9s/plugins.yaml 中加入：
plugins:
gonzo:
shortCut: Ctrl-L
description: "Gonzo log analysis"
scopes: [po]
command: sh
background: false
args:
- -c
- "kubectl logs -f --tail=0 $NAME -n $NAMESPACE --context $CONTEXT | gonzo"
进入 k9s 选中 Pod，按 Ctrl-L 即可打开 Gonzo 并开始实时分析。(GitHub)
九、适配任意日志格式（YAML 自定义）
- 为复杂 / 批量格式（如 Loki stream）提供 自定义格式，在
~/.config/gonzo/formats/放置 YAML 并指定--format使用；支持字段映射、嵌套 JSON 提取、批量展开与基于正则的非结构化解析。
# 例：使用内置 Loki 示例（先把示例 YAML 放到 config 目录）gonzo --format=loki-stream -f loki_logs.json
定制方法见“Custom Formats Guide”。(GitHub)
十、配置文件（持久化首选项）
默认位置：~/.config/gonzo/config.yml，示例字段：
files:
- "/var/log/app.log"
- "/var/log/*.log"
follow: true
update-interval: 2s
log-buffer: 2000
memory-size: 15000
skin: dracula
stop-words: ["log", "message", "debug"]
ai-model: "gpt-4"
也支持通过环境变量（如 GONZO_FILES、GONZO_AI_MODEL 等）覆盖。(GitHub)
十一、生产与团队实践建议
- 性能：尽量以文件跟随或 OTLP 直连方式采集；合适地调大
log-buffer、降低update-interval抖动；Release 构建。(GitHub) - 可观测性体系：与 Victoria Logs/OTLP Collector 配合做集中采集，再用 Gonzo 做“临场 TUI 研判”。(GitHub)
- 隐私 / 合规 ：使用本地模型（Ollama / LM Studio）可在 无外传 前提下做 AI 洞察。(GitHub)
- K8s 工作流：配合 k9s 插件，按 Pod/ 命名空间精确拉流，减少“人肉定位”时间。(GitHub)
常见问题（速览）
- 看不到模型 / 无法切换：确认 AI 服务可用、BASE URL 正确（LM Studio 需要
/v1后缀；Ollama 无/v1），按m打开模型选择面板。(GitHub) - 日志格式混杂：先让 Gonzo 自动检测（JSON/logfmt/text）；复杂格式用自定义 YAML。(GitHub)
- 从 0 到可视化太慢？ 使用 Collector/
kubectl logs -f直接流式进入 Gonzo，减少中转。(GitHub)
参考与下载
- 官方站（特性总览、三行安装、快速指令）：Gonzo Landing Page。(gonzo.controltheory.com)
- GitHub 仓库（README、安装、用法、格式 /AI 配置、快捷键）：control-theory/gonzo。(GitHub)
- Releases（最新版本 / 变更日志，含 Victoria Logs 支持、主题 / 严重级别筛选等）：(GitHub)
- 进阶指南：CloudWatch、Stern、Victoria Logs。(GitHub)
正文完
