Kula 是一款轻量级的 Linux 服务器监控工具，除了内置的 CPU、内存、磁盘、网络监控外，它的自定义指标功能可以图表化任何你能测量的数据。本教程教你如何用一条 Unix Socket 命令，把风扇转速、室温、电压等传感器数据推送到 Kula，自动变成实时监控图表。

工作原理：为什么是 Unix Socket？

Kula 的设计非常简洁：

1. 你在配置文件里声明"我要看什么"（图表组 + 指标名称 + 单位 + 最大值）
2. Kula 启动后自动创建一个 Unix Socket 文件，默认位于<storage.directory>/kula.sock（例如/var/lib/kula/kula.sock）
3. 任何脚本或程序把 JSON 数据写入这个 Socket，Kula 就把它画成图

因为只监听本机 Socket、不额外开放网络端口，所以它既简单又安全。配置示例可以参考 config.example.yaml 中applications.custom部分的注释。

第一步：在配置文件中定义图表组

编辑config.yaml，在applications下添加custom配置。以"CPU 风扇 + 房间温度"为例：

applications: custom: cpu_fans: - name: fan1 unit: RPM max: 5000 - name: fan2 unit: RPM max: 10000 room_temp: - name: ambient unit: °C max: 50

三个字段各管各的事：

规则很好记：每个组（group）变成一张图表卡片，组里每个指标变成卡片上的一条曲线。cpu_fans组就会是一张包含 fan1、fan2 两条线的转速图。

第二步：向 Socket 发送数据

数据格式是"换行分隔的 JSON"，custom字段下面，组名对应一个[{指标名: 数值}]数组。最快捷的方式是配合socat一行命令：

echo '{"custom":{"cpu_fans":[{"fan1":4423},{"fan2":8512}]}}' \ | socat - UNIX-CONNECT:/var/lib/kula/kula.sock

想持续监控？把读取传感器的部分放进循环即可，推送节奏建议与 Kula 的collection.interval保持一致（例如每秒一次）：

SOCK=/var/lib/kula/kula.sock while true; do rpm1=$(cat /sys/class/hwmon/hwmon0/fan1_input 2>/dev/null || echo 0) printf '{"custom":{"cpu_fans":[{"fan1":%s}]}}' "$rpm1" \ | socat - UNIX-CONNECT:"$SOCK" sleep 1 done

Kula 仓库自带了一份 Python 参考脚本 scripts/custom_example.py，展示了如何直接用 socket 库连接并发送一条 JSON，你可以照着自己的传感器改写。实际上，任何能写 Unix Socket 的语言都可以——Python、Shell、Go、C 都行。

第三步：打开看板，图表自动出现

数据一到，新图表卡片会自动出现在 Web 仪表盘的Applications分区下，无需其他操作。自定义指标和内置指标一样存储在 Kula 的分层环形缓冲（tiered ring-buffer）里，所以：

• ✅ 有完整历史，支持按 1 分钟/5 分钟聚合的回看视图
• ✅ 时间范围切换（1m ~ 30d）同样适用
• ✅ 可以导出到 Prometheus（如果开启了prometheus_metrics）

常见问题与最佳实践

🔍 图表没出现？

• 组名、指标名必须与配置完全一致——未声明的名字会被静默忽略
• 确认 Socket 路径：默认在storage.directory下；如果 Kula 因权限不足回退到了~/.kula，Socket 就在那里
• Socket 权限为0660（属主 + 属组可写），普通用户发送时可能需要加入kula组

📉 曲线断开了？

Kula 有"过期检测"：数据源停止推送后，图表会显示空档而不是冻结在最后一条值上（这通常更符合真实情况）。默认窗口约为 5 个采集周期，可用applications.custom_stale_after: 10s调整。

⚠️ 几个限制要记住

• 每条消息最多64 KB，一行一个 JSON 对象
• 数值可以是整数或浮点数；同一条消息里重名指标只保留最后一个值
• 组名和指标名要保持稳定，它们是图表的键
• 空闲超过 5 分钟的连接会被自动关闭
• Socket 同一时间只有一个进程持有，重复启动的 Kula 会放弃自定义指标而不是抢占

更多细节可查阅官方文档 docs/user/09-custom-metrics.md，核心实现位于 internal/collector/custom.go。

可以玩出什么花样？

自定义指标几乎不设限，几个灵感：

• 🌡️NAS/矿机机房：USB 温度探头读数、UPS 电池电压
• 🎮游戏主机：手柄电池、下载速度统计
• 📊应用监控：脚本计算的 QPS、队列长度、爬虫抓取数
• 💡智能家居：Home Assistant 暴露的任意传感器

只要你能从一个文件、API 或设备里"读"出一个数字，就能把它变成 Kula 看板上的实时图表。配置一次，脚本常跑，剩下的交给 Kula。