sampler 1.1.0 配置参数详解

目标：逐项讲清 sampler 1.1.0 的 YAML 配置文件——顶层结构、通用参数、六大组件专有参数、变量系统、触发器、交互 shell，并给出全部经实测的报错速查表与一份生产配置模板。文中所有参数行为、报错回显与界面画面均在 Ubuntu 22.04 服务器实测（2026-10-23），实现细节对照 v1.1.0 官方源码核实。安装步骤见《Ubuntu 22.04 安装 sampler 1.1.0 指南》，组件定位与选型见《sampler 介绍与选型指南》。

一、配置文件定位与加载流程

sampler 只有一种配置形态：启动时用 -c 显式指定的单个 YAML 文件。不存在系统级或用户级配置文件，不传 -c 会得到提示后退出（退出码 0）：

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

加载流程为：解析命令行 → 读取 YAML 文件 → 反序列化并校验（title 唯一性、sample 必填、init 互斥）→ 填充默认值 → 进入全屏 TUI。画布为 80 列 × 40 行字符的虚拟坐标，组件用 position 在其上布局。

最小可用配置（本文的基准探针，保存为 config.yml）：

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}'

在真实终端（SSH 会话或 tmux）里运行 sampler -c config.yml 即可看到负载曲线；按 q 退出。

💡 实测判据：在无终端环境（如 CI 脚本、管道）里执行配置探针时，输出 Failed to initialize ui: open /dev/tty: no such device or address（退出码 1）说明 YAML 已通过校验、程序走到了界面初始化；这一现象被用作本文所有配置文件的「校验通过」判据。若在 tmux 中复现本文界面，建议会话尺寸不小于 80×40（tmux new-session -x 80 -y 40）——实测 80×24 的窄终端会把 40×6 的 textbox 压缩成 3 行高的空框，内容区不足一行导致文字不显示。

二、顶层结构总览

配置文件顶层共有 8 个键（对照 v1.1.0 源码 config 结构核实）：

每个组件键都是数组，可同时放多个组件；组件 title 在整个配置内必须全局唯一。

⚠️ 注意：1.1.0 没有 meters 组件（官方仓库主干上的 meters 功能未随 v1.1.0 发布，README 新版截图中的 meters 不适用于 1.1.0）。另外 YAML 未知的顶层键不会报错而是被静默忽略——实测把 runcharts 拼成 runcarts 后程序把它当作空配置，启动即 panic（退出码 2），报错速查见第十节。

三、通用参数（所有组件共享）

position 写法实测示例（本配置 6 组件占满 80×40 画布，见第十一节）：position: [[44, 0], [24, 12]] 表示从第 44 列第 0 行起、宽 24 高 12。

四、数据采集参数（Item 级）

以下参数出现在组件的 items 条目上（runcharts/barcharts），或直接内联在组件上（sparklines/textboxes/asciiboxes/gauges 的 cur/max/min）：

sample 输出的数值解析规则（源码核实）：对图表/仪表类组件，程序取输出做「去首尾空白 → 逗号转小数点 → 多行取最后一行」后解析为浮点数。因此：让 sample 尽量只输出一个数；输出带千分位或逗号小数（如 1,5）也能解析。

transform 参数重大限制（实测发现）：v1.1.0 中 transform 脚本（收到 sample=<原始输出> 环境变量）只在配置了 init/multistep-init 或 pty 的交互 shell 路径上被调用；普通一次性 sample 的执行路径不经过 transform。实测证据：textbox 配 sample: echo 'up 3 days' + transform: echo "raw=[$sample]"，界面显示的仍是原始输出 up 3 days 而非 raw=[up 3 days]（源码中 transform 调用仅存在于交互会话执行器内）。想加工普通 sample 的输出，直接在 sample 命令里用管道完成（awk/sed）。

五、六大组件专有参数

以下配置片段均取自第十一节生产模板（全模板已实测通过校验并运行）。

5.1 runcharts（折线时序图）

runcharts:
  - title: LOAD AVERAGE
    position: [[0, 0], [44, 12]]
    rate-ms: 1000
    scale: 2
    legend:
      enabled: true
      details: false
    items:
      - label: LOAD 1M
        sample: cat /proc/loadavg | awk '{print $1}'
        color: 39
      - label: LOAD 5M
        sample: cat /proc/loadavg | awk '{print $2}'
        color: 178

• scale：曲线数值保留小数位，默认 1；
• legend.enabled：是否显示图例（默认 true）；legend.details：图例中是否带 cur/min/max/dlt 统计（默认 true，实测关掉后图例只剩标签）；
• X 轴时间刻度按 rate-ms 自动标定取整到秒；曲线为盲文点阵字符渲染；
• 未指定 color 时按 items 顺序从主题调色板轮转取色（dark 主题首三个为 178/39/198）。

5.2 barcharts（柱状图）

barcharts:
  - title: DIR SIZE (MB)
    position: [[22, 12], [22, 6]]
    scale: 0
    items:
      - label: usr
        sample: du -sm /usr 2>/dev/null | awk '{print $1}'
      - label: var
        sample: du -sm /var 2>/dev/null | awk '{print $1}'
      - label: etc
        sample: du -sm /etc 2>/dev/null | awk '{print $1}'

scale 控制柱顶数值小数位（默认 1，上例取整）。实测画面中三根柱按数值降序排列、柱顶标数值、柱底标 label。

5.3 sparklines（迷你趋势图）

sparklines:
  - title: CPU LOAD
    position: [[44, 0], [24, 12]]
    rate-ms: 1000
    scale: 1
    sample: cat /proc/loadavg | awk '{print $1*100}'

单采样组件，sample 直接内联在组件上；渐变色不接受配置——由程序按主题自动分配（dark 主题预置两组渐变色序），label 默认取 title。实测画面为竖向渐变柱逐帧滚动并在右上角显示当前值（如 315）。

5.4 gauges（仪表盘）

gauges:
  - title: ROOT DISK USED
    position: [[0, 12], [22, 6]]
    cur:
      sample: df / | tail -1 | awk '{print $5}' | tr -d '%'
    max:
      sample: echo 100
    min:
      sample: echo 0

• cur/max/min 三个子采样分别提供当前值、上限、下限，各自都是完整 Item（可用 init/transform 等）；
• percent-only：默认 false，同时显示百分比与当前值（实测画面 62% (62)）；置 true 只显示百分比；
• color：仪表填充色，默认按调色板轮转；scale 控制百分比小数位（默认 1）；
• 三个子采样的 label 被程序固定为 cur/max/min——这是触发器里 $label 变量的取值来源（见第八节）。

5.5 textboxes（文本框）

textboxes:
  - title: SYSTEM INFO
    position: [[0, 18], [68, 6]]
    rate-ms: 5000
    sample: uname -sr && uptime && whoami

原样展示多行输出（自动换行、自动剥离 ANSI 色码）。border 默认 true，置 false 去边框；color 默认为主题基准色（dark 为 15 号白）。实测画面正常显示三行系统信息。

5.6 asciiboxes（ASCII 大字）

asciiboxes:
  - title: SERVER TIME
    position: [[44, 12], [24, 6]]
    rate-ms: 1000
    sample: date +%H:%M:%S
    font: 3d

把单行文本用 ASCII 字符画放大。font 仅两种：2d（默认）与 3d（实测 3d 为带阴影的立体字）；border 默认 true；color 默认白色；label 默认取 title。

六、主题与颜色

theme 只接受 dark（默认）与 light 两个值。实测其他值（theme: blue）启动即 panic，退出码 2：

panic: Specified theme is not supported: blue

color 必须是 8-bit 色号整数（0-255）。实测字符串形式的 notacolor、red、"39"、#ff0000 全部被拒绝，报错格式一致（退出码 1）：

Failed to read config file: yaml: unmarshal errors:
  line 8: cannot unmarshal !!str `notacolor` into termui.Color

dark 主题的调色板（未写 color 时按此顺序轮转，对照源码核实）：

light 主题内容色为 0/88/57/242/64 五色。终端需支持 256 色（建议 TERM=xterm-256color），否则色号映射会失真。

七、变量系统

三处来源按优先级叠加（低 → 高）：系统环境变量 → 配置内 variables → 命令行 -e。同名变量高优先级覆盖低优先级（源码合并顺序核实 + 实测 -e vtest=fromcli 覆盖配置内同名变量，采样进程 env dump 显示 vtest=fromcli）。

variables:
  disk_path: /

变量以普通环境变量形式注入 sample / init / transform 进程（实测：采样进程 env dump 落盘后可见 tvar=fromcfg），在命令里用 $disk_path 引用（见 5.4 的 gauge 示例）。

⚠️ 实测发现：触发器进程不注入配置内 variables。实测触发器条件里 env 落盘后只有 cur/prev/label 与系统环境变量，没有 tvar。触发器里要用自定义变量，只能靠命令行 -e 或系统环境变量（-e 会注入触发器进程，源码与实测一致）。

八、触发器（triggers）

触发器挂在组件级，每次该组件采样后执行，可实现告警与外部动作：

triggers:
  - title: LOAD 1M OVER 2
    condition: 'echo $cur | awk "{if (\$1 > 2) print 1; else print 0}"'
    actions:
      visual: true
      terminal-bell: true

条件进程可用的变量：$cur（本次采样原始输出）、$prev（上次采样值，首次采样为 "0"）、$label（采样条目 label；gauge 组件固定为 cur/max/min）。实测脚本动作确实收到三个变量（脚本落盘验证：label=P1 cur=42 prev=0）。

⚠️ 换行符陷阱（实测发现，官方示例写法失效）：$cur/$prev 保留 sample 原始输出的行尾换行符——echo 42 的 $cur 实测为 3 字节 42\n。官方 README 的 condition: echo "$cur > 0.5" | bc -l 写法因此失效：拼接后 bc 收到两行输入（42 与 > 0.5），第一行被当作表达式直接求值输出 42，第二行语法错误（stderr 报 (standard_in) 2: syntax error），比较从未发生；剔除非数字后得 42 ≠ 1，触发器恒判假。实测可用的两种写法：

写法一（awk，推荐）：

condition: 'echo $cur | awk "{if (\$1 > 0.5) print 1; else print 0}"'

写法二（printf 去换行后交 bc）：

condition: 'printf "%s > 0.5\n" "$(echo $cur | tr -d "\n")" | bc -l'

两者在 $cur=42\n 时实测均正确输出 1。注意条件脚本由 sh -c 执行且 YAML 值含引号，建议整值用 YAML 单引号包裹（见第十二节 FAQ）。

condition 自身运行失败（命令报错、非数字输出异常）不会终止程序：组件顶部会显示 TRIGGER CONDITION FAILURE 告警条（实测画面），条件恢复后自动消失。

九、交互 shell（init / multistep-init）

普通 sample 每次采样都新起一个 sh -c 进程。若要在一个常驻会话里反复采样（连数据库客户端、SSH 远程机器、进入应用管理控制台等场景），用 init 或 multistep-init：

textboxes:
  - title: SESSION PROBE
    position: [[0, 0], [40, 6]]
    rate-ms: 1000
    multistep-init:
      - sh
      - export MSG=hello-sampler
    sample: echo $MSG

实测行为：首条 sh 起常驻会话，第二条 export MSG=hello-sampler 写入该会话，之后每次采样把 sample 命令写入会话执行——界面稳定显示 hello-sampler，证明变量在会话内持久生效。

规则与边界（源码核实 + 实测）：

• init 与 multistep-init 互斥，同时出现报 Config validation error: both init and multistep-init scripts are not allowed for 'X'（退出码 0）；
• multistep-init 的后续每条命令写入会话后间隔约 200ms 再执行下一条（源码常量），长耗时的初始化命令要留意；
• 会话内单次采样的等待超时为 rate-ms × 3/4，超时未拿到输出按失败计；连续失败 10 次程序会重启会话（源码 errorThreshold）；
• pty: true 把会话换成伪终端形态，适合需要在真实 TTY 里运行的交互程序；
• 远程场景：官方 README 的用法是在 init 里 ssh user@host 登录远程服务器，sample 命令即在远端执行——本地只跑一个 sampler 即可观测多台机器。

十、配置校验规则与报错速查表

以下 10 类全部在 Ubuntu 22.04 实测，回显逐字实录：

注意退出码的三种形态：YAML/解析类错误为 1；空组件与主题类 panic 为 2；而第 6-9 类校验错误退出码是 0（实现按成功状态退出）——用脚本预检配置时不能依赖退出码判断校验是否通过，要抓 Config validation error 字样。

十一、生产配置模板（全文实测）

以下模板覆盖全部 6 类组件、变量、触发器与 80×40 画布布局，已实测通过校验并连续运行（界面实录见各组件小节）。注意触发器条件用的是第八节实测可用的 awk 写法，而非官方 README 中失效的 bc 直拼写法：

theme: dark
variables:
  disk_path: /
runcharts:
  - title: LOAD AVERAGE
    position: [[0, 0], [44, 12]]
    rate-ms: 1000
    scale: 2
    legend:
      enabled: true
      details: false
    items:
      - label: LOAD 1M
        sample: cat /proc/loadavg | awk '{print $1}'
        color: 39
      - label: LOAD 5M
        sample: cat /proc/loadavg | awk '{print $2}'
        color: 178
    triggers:
      - title: LOAD 1M OVER 2
        condition: 'echo $cur | awk "{if (\$1 > 2) print 1; else print 0}"'
        actions:
          visual: true
          terminal-bell: true
sparklines:
  - title: CPU LOAD
    position: [[44, 0], [24, 12]]
    rate-ms: 1000
    scale: 1
    sample: cat /proc/loadavg | awk '{print $1*100}'
gauges:
  - title: ROOT DISK USED
    position: [[0, 12], [22, 6]]
    cur:
      sample: df $disk_path | tail -1 | awk '{print $5}' | tr -d '%'
    max:
      sample: echo 100
    min:
      sample: echo 0
barcharts:
  - title: DIR SIZE (MB)
    position: [[22, 12], [22, 6]]
    scale: 0
    items:
      - label: usr
        sample: du -sm /usr 2>/dev/null | awk '{print $1}'
      - label: var
        sample: du -sm /var 2>/dev/null | awk '{print $1}'
      - label: etc
        sample: du -sm /etc 2>/dev/null | awk '{print $1}'
asciiboxes:
  - title: SERVER TIME
    position: [[44, 12], [24, 6]]
    rate-ms: 1000
    sample: date +%H:%M:%S
    font: 3d
textboxes:
  - title: SYSTEM INFO
    position: [[0, 18], [68, 6]]
    rate-ms: 5000
    sample: uname -sr && uptime && whoami

十二、FAQ

Q1：title 里带冒号就报 mapping values are not allowed in this context？ YAML 语法问题：未加引号的值里出现「: 」会被解析器当作键值分隔。实测 title: COLON: TEST 报 Failed to read config file: yaml: line 2: mapping values are not allowed in this context（退出码 1）。解决：值用引号包裹，如 title: 'COLON: TEST'。

Q2：触发器条件里能用配置 variables 的变量吗？ 不能（实测，见第七节）。触发器进程只收到系统环境变量、-e 指定变量和 cur/prev/label。把变量改经 -e 传入即可（-e 优先级最高且三处进程都注入）。

Q3：awk 条件里写三元运算符报语法错？ Ubuntu 默认 awk 是 mawk，不支持 cond ? a : b 三元写法（实测报语法错误）。用 if (...) print 1; else print 0 形态（本文所有示例即此形态）。

Q4：sample 输出多行为什么图表数值不对？ 数值解析只取最后一行（源码规则，见第四节）。多行输出请先在 sample 里用 awk/tail 过滤出目标数值。

Q5：为什么我的 transform 不生效？ transform 只对配置了 init/multistep-init（或 pty: true）的交互式组件生效；普通一次性 sample 的执行路径不经过 transform（实测与源码双重确认，见第四节）。普通组件请把加工逻辑直接写进 sample 命令。

Q6：终端尺寸有要求吗？ 画布按 80×40 设计。实测在 80×24 的窄终端里组件布局被压缩，矮组件（如 40×6 的 textbox）内容区不足一行导致只有框没有字（见第一节实测说明）。建议 tmux 用 new-session -x 80 -y 40，或使用全屏终端。

十三、参考链接

1. 官方仓库与配置文档（README）：https://github.com/sqshq/sampler
2. v1.1.0 源码（本文实现细节核对基准）：https://github.com/sqshq/sampler/tree/v1.1.0
3. 系列文档：《sampler 介绍与选型指南》《Ubuntu 22.04 安装 sampler 1.1.0 指南》《sampler 1.1.0 常用 CLI 命令与工具详解》（见 sampler 专栏）