sampler 介绍与选型指南

目标：讲清 sampler（sqshq/sampler）这一「配置驱动的终端命令输出可视化工具」的定位、架构、功能与维护现状，并与 bottom、gtop、glances、dstat 做量化选型对比，帮助读者判断「什么场景该选 sampler、什么场景不该选」。本文为认知篇，全部事实性内容（版本、星数、许可证、发布节奏、维护状态）均来自官方仓库与官方发行渠道联网溯源，溯源来源与查询日期见「一、环境信息」。

一、环境信息

本篇为认知篇，不依赖本机实验环境；下列事实均于 2026-10-23 通过公开渠道联网溯源取得，来源如下：

💡 说明：GitHub API 直连（api.github.com）存在匿名限流，本篇星数取自 shields.io 徽章接口（https://img.shields.io/github/stars/sqshq/sampler.json，实测返回 {"label":"stars","message":"15k",...}）；许可证与官方主页取自 Homebrew 官方 formula 元数据（https://formulae.brew.sh/api/formula/sampler.json），与仓库元数据同源。

维护状态必须如实说明：截至查询日期 2026-10-23，sampler 的最新稳定版仍是 2019-12-24 发布的 v1.1.0，此后六年多没有任何新版本发布；仓库 README 的安装章节仍指向 v1.0.3 的下载链接，说明文档层面也长期未维护。v1.1.0 的 Release Notes 只有两句话：「Minor bugfixes」「Get rid of all server-side interactions」（移除了全部服务端交互，即工具不再向作者服务器回传数据）。因此 sampler 应被定性为「功能完整但停止演进」的工具：现有能力可用、可复制，但不承诺修复新问题，选型时必须把「无人维护」作为前提条件评估。

二、软件概述

sampler 是 sqshq 团队（GitHub 组织 sqshq）于 2019 年发布的开源命令行工具，仓库地址 github.com/sqshq/sampler，Go 语言编写，GPL-3.0 许可证。用官方 README 的自述来说，它是一个「shell 命令执行、可视化与告警工具」，用一个简单的 YAML 文件完成全部配置。

它的定位与常规监控工具相反：常规工具（htop、bottom、glances）先内置好「看什么」，sampler 让你先决定「看什么」。任何能通过 shell 命令取到的值——数据库行数、消息队列堆积量、某个接口的耗时、日志关键字出现次数——只要把命令写进 YAML 的 sample 字段，sampler 就按指定频率反复执行该命令，把输出画成折线图、面积图、柱状图、仪表盘、大字 ASCII 码或文本框，并可在数值越限时触发响铃、提示音、屏内告警或任意脚本动作。官方 README 对此的表述是：「If there is a way to get a metric using a shell command - then it can be visualized with Sampler momentarily.」

这一定位有三个关键词：

1. 配置驱动：界面上有什么组件、每个组件执行什么命令、多久刷新一次、用什么颜色，全部由一份 YAML 决定，零代码。配置文件可以纳入版本管理，一台服务器的仪表盘就是一份可审计的文件。
2. 零服务端：单二进制、单进程、无守护进程、无数据库、无 Web 服务。官方明确它不是 Prometheus + Grafana 的替代品，而是「 spinning up 监控系统属于杀鸡用牛刀」场景下的轻量开发/运维工具。
3. TUI 呈现：基于 termui/termbox 在字符画布上渲染，SSH 到任意服务器都能跑，不依赖图形环境；组件位置与尺寸可以直接在界面上用方向键拖拽调整，退出时自动回写配置文件。

💡 技术拓展：sampler 的折线图用「盲文点阵（braille）」字符绘制，同为字符画布的时序呈现方案，业界还有几种常见方式，横向对比——

呈现方式	原理	效果与取舍	代表工具
盲文点阵 braille	用 U+2800 区盲文字符的 2×4 点位拼图形	曲线平滑、信息密度高	sampler、bottom（默认）
块状字符 block	用 ▎/█ 等块字符拼柱形/面积	简洁直观，适合速率/占比	sampler（sparkline/gauge）、btop
ASCII 大字	用 figlet 字体把文本渲染成字符画	无「图」，胜在醒目	sampler（asciibox）
表格滚动	直接滚动输出文本	零渲染成本，无趋势	watch、dstat

sampler 同一组件体系内同时支持 braille 折线、块状面积/仪表与 ASCII 大字三种形态，由组件类型选择，无需更换工具。

三、核心架构

sampler 的架构可以用「单二进制、单进程、零依赖外部服务」概括（依据 v1.1.0 源码结构与 README，溯源日期 2026-10-23）：

1. 采集层：启动后按配置中每个组件的 rate-ms（默认 1000ms）周期执行其 sample 命令。命令统一经 sh -c 执行，因此任何 POSIX shell 语法都可用（管道、awk、cut 等）；执行环境注入配置 variables 与 -e 命令行变量，以及系统环境变量。对需要「先登录再轮询」的场景（数据库 CLI、SSH 会话），提供 init/multistep-init 建立持久交互会话（可选 pty: true 伪终端模式），sample 命令在同一会话内反复执行。
2. 解析层：命令原始输出先经 vtclean 库剥离 ANSI 颜色码，再交给组件消费。数值型组件（折线图/柱状图/仪表/面积图）用统一的数值解析：先去除首尾空白、把小数逗号换小数点，若输出多行则取最后一行——所以命令直接输出 awk 单值即可，多行输出会取尾行。
3. 呈现层：基于 termui v3 / termbox 在终端字符画布渲染，内置 dark/light 两套配色主题；六个组件类型按 YAML 的 position: [[x, y], [w, h]] 摆放，未写 position 时由内置算法自动排布（先按 80×40 的虚拟画布计算最大空白矩形，再决定分割最大组件还是填入空白区）。
4. 交互层：全键盘（p 暂停、方向键选中组件、Enter 打开 MOVE/RESIZE/PINPOINT 菜单、ESC 清除告警、q/Ctrl-c 退出）+ 鼠标点击选中。移动/缩放组件后退出，sampler 会把新布局以 YAML 形式回写进原配置文件——布局调整即持久化，这是它「配置驱动」闭环的最后一块。
5. 告警层（triggers）：每个组件可挂任意条触发器，condition 也是一条 shell 命令（收到 $cur/$prev/$label 三个环境变量），输出经「剔除非数字字符后等于 1」判定为真；命中后可执行四种动作的组合：终端响铃（terminal-bell）、提示音（sound，NASA quindar 音，需要 ALSA 声卡设备）、组件内可视化告警（visual）、任意脚本（script，同样收到 $cur/$prev/$label）。

两点架构上的「没有」同样重要，直接影响选型：

• 没有历史存储与回看：时序数据只在内存里滚动，退出即丢，不落盘、不接时序数据库，没有 HTTP API 供外部拉取。要长期留存指标必须自行在 script 动作里落文件，或换 Prometheus 体系。
• 没有自动采集的内置指标：sampler 自身一个指标都不「懂」，CPU、内存、磁盘全靠你写的命令（cat /proc/loadavg、df、free 等）。好处是零学习成本且能看任何东西；代价是所有仪表盘都要自己动手搭。

四、功能特性

以下特性清单来自官方 README 与 v1.1.0 程序自述（--help 输出见本系列《sampler 1.1.0 常用 CLI 命令与工具详解》篇逐字实录），溯源日期 2026-10-23：

⚠️ 注意：v1.1.0 的 sample 原始输出保留行尾换行符，触发器 condition 中直接以 "..." 引用 $cur 时会把换行一并代入命令，导致官方 README 示例中的 echo "$cur > 0.8" | bc -l 写法实际失效（bc 收到两行输入报语法错误）。本系列《sampler 1.1.0 配置参数详解》篇对该问题做了逐字节复现，并给出两种实测可用的可靠写法——这是阅读旧教程时最容易踩的坑。

五、快速开始（最小可用示例）

在 Ubuntu 22.04 服务器上，安装完成后写一个最小的 config.yml 即可启动（安装全过程与逐条实测回显见本系列《Ubuntu 22.04 安装 sampler 1.1.0 指南》篇）：

# 安装（官方二进制路径，完整步骤见安装指南篇）
sudo wget https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-linux-amd64 -O /usr/local/bin/sampler
sudo chmod +x /usr/local/bin/sampler
sudo apt-get install -y libasound2   # 运行前置：ALSA 用户态库
sampler -v                           # 验证

实测版本回显：

1.1.0

写一个最小配置（每秒采样系统 1 分钟平均负载并画成折线图）：

runcharts:
  - title: LOAD AVERAGE
    position: [[0, 0], [40, 10]]
    rate-ms: 1000
    scale: 2
    items:
      - label: LOAD 1M
        sample: cat /proc/loadavg | awk '{print $1}'

启动：

sampler -c config.yml

该配置已在真实环境实测：程序进入全屏 TUI，标题栏显示 sampler 1.1.0 @ /root/t/ok-minimal.yml，LOAD AVERAGE 组件内以盲文点阵绘制负载曲线，Y 轴自动标定数值、X 轴以 HH:MM:SS 时间刻度滚动；按 q 退出。两点实测注意事项：

1. 必须在真实终端（TTY）运行：在无终端的后台环境执行会得到如下实测回显后退出（退出码 1）：

2026/10/23 04:03:17 Failed to initialize ui: open /dev/tty: no such device or address

2. -c 是必填参数：不指定配置文件直接运行 sampler，得到如下实测提示（注意退出码为 0，这是该版本的一个小怪癖）：

Please specify config file using --config flag. Example: sampler --config example.yml

六、适用场景与限制

适合的场景：

1. 临时排障与调参观察：压测时盯一条自定义指标（接口耗时、队列深度、连接数），一条命令 + 一份小配置立即见效，无需部署任何监控系统。
2. 数据库/中间件会话内轮询：通过 init 一次建立 mysql/psql/mongo/kafka-consumer-groups 会话，反复执行查询并可视化，避免每次采样都重建连接（官方 README 提供了五类配方）。
3. 多机 SSH 聚合视图：在本机终端用多个 textbox/组件 + init: ssh ... 拼出跨机器仪表盘。
4. 大屏/值班终端：asciibox 大字 + 仪表盘 + 触发告警，挂在 tmux 窗格里当低成本的值守面板。
5. 配置即文档：仪表盘定义是纯 YAML，可进 Git、可评审、可在团队内复用。

限制（选型前必须接受）：

1. 项目停止演进：最新稳定版 2019-12-24 发布，六年多无更新；遇到新系统/新终端的兼容问题基本只能自行改源码或寻找 fork。
2. 无历史、无 API、无集群视角：内存时序、退出即丢；不适合需要长期留存、检索、多实例汇总的监控需求。
3. 单机 TUI 形态：没有 Web 界面，不能多人共享同一视图（tmux share 除外）；通知手段限于终端响铃/提示音/屏内告警/脚本，没有邮件、IM 推送等现成通道（都要靠 script 动作自己写）。
4. 触发器有换行符陷阱：官方文档示例的 condition 写法在 1.1.0 实际不可用（见第四节注意事项），需要按配置篇给出的修正模式书写。
5. 数值解析宽容但有边界：多行输出取最后一行、小数逗号自动转点，但样本必须是「能被 ParseFloat 解析」的纯数值（图表类组件），文本类场景要用 textbox/asciibox。

七、同类选型对比

sampler 的生态位是「自定义指标的可视化」。最容易被一起比较的有三类：同为终端 TUI 的系统监控器（bottom、gtop）、带服务端能力的综合监控器（glances）、以及命令列式的多资源统计器（dstat）。下表按可量化维度对比（版本与星数均为 2026-10-23 通过 shields.io 徽章与官方 Releases 实查；bottom/glances/gtop 的详细对比见站内对应专栏）：

关键差异与选型建议：

1. 要看的指标不在内置清单里 → sampler。bottom/gtop/glances/dstat 的共同前提是「看系统指标」；一旦要看的是业务指标（某 API 的耗时、某张表的行数、某个队列的堆积），它们没有任何扩展点，而 sampler 的 sample 命令天然覆盖「shell 能拿到的一切」。这也是它与其他四者本质上不冲突的原因——常见组合是 glances/bottom 看系统健康，sampler 看业务与中间件。
2. 要开箱即用的系统全景 → bottom 或 glances。sampler 不内置任何指标，新装一台服务器想要立刻看到 CPU/内存/网络，写配置不如直接跑 [《bottom 介绍与选型指南》](https://www.quzuo.net/document/QoUzLDAxCZMp) 里的 btm 或 glances；需要 Web 端与 C/S 远程能力时选 [《glances 介绍与选型指南》](https://www.quzuo.net/document/umdFmBPimmP4)。
3. 喜欢炫彩仪表盘但不改内容 → gtop。gtop 的视觉与 sampler 最接近（同为组件化 TUI），但组件不可自定义；看惯了即可，深度定制无门（详见 [《gtop 介绍与选型指南》](https://www.quzuo.net/document/xYqWjz2lHn59)）。
4. 要列式计数器与 CSV 存档 → dstat 已终止开发，其维护续作是 dool；新项目不建议再引入 dstat 本体。
5. 能接受停止演进的自定义可视化 → sampler 是该生态位唯一轻量选项。在「纯终端 + 配置文件 + 任意 shell 命令」这个组合上，暂无同等体量的活跃替代品（Prometheus + Grafana 是功能上溢出但重量完全不同的方案）。接受其维护冻结、把配置纳入版本管理、触发器按修正写法书写，sampler 在小团队/单机场景仍然是高性价比工具。

八、参考链接

1. 官方仓库与源码：https://github.com/sqshq/sampler
2. 版本发布（Releases）：https://github.com/sqshq/sampler/releases
3. 官方主页：https://sampler.dev
4. 本系列安装篇：《Ubuntu 22.04 安装 sampler 1.1.0 指南》（见 sampler 专栏）
5. 本系列配置篇：《sampler 1.1.0 配置参数详解》（见 sampler 专栏）
6. 本系列命令篇：《sampler 1.1.0 常用 CLI 命令与工具详解》（见 sampler 专栏）
7. 站内同类工具：《bottom 介绍与选型指南》、《glances 介绍与选型指南》、《gtop 介绍与选型指南》