Riemann 0.3.12 常用 CLI 命令与工具详解

目标：讲清 Riemann 0.3.12 生态里日常运维要用的全部命令行工具与接口——riemann launcher（-v/test/start/reload）、riemann-client（C 客户端 1.10.4 的 send/query）、HTTP/SSE 通道（POST /events、GET /index）、查询 DSL 操作符实测、systemd 服务管理与 jps -v JVM 堆验证，并完整沉淀 riemann-dash 的排障实录。全部命令与回显均已在 Ubuntu 22.04.5 + Riemann 0.3.12 服务器环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Jammy，x86_64）
Riemann 版本：0.3.12（deb 安装，安装过程见《Ubuntu 22.04 安装 Riemann 0.3.12 指南》）
Java 运行时：OpenJDK 11.0.32.1（jps 来自 default-jre-headless）
C 客户端：riemann-c-client 1.10.4（apt 包，提供 /usr/bin/riemann-client）
配置文件：/etc/riemann/riemann.config（本文实测基于配置详解篇第七章的生产配置，事件均带 c1 标签流）
监听端口：5555/TCP+UDP、5556/HTTP+WS、5557/SSE、2003/Graphite、4242/OpenTSDB
服务主机名：riemann-srv；JVM 堆：-Xms256m -Xmx512m（/etc/default/riemann）

二、工具概览

工具/命令	来源	用途	本文章节
`riemann`	deb 包 `/usr/bin/riemann`	launcher：版本查询、配置校验、前台启动	四
`riemann-client`	apt 包 `riemann-c-client` 1.10.4	命令行发送/查询事件（TCP/UDP）	五
`curl` + HTTP 5556	Riemann 内置 ws-server	NDJSON 事件注入 `POST /events`	六
`curl` + SSE 5557	Riemann 内置 sse-server	`GET /index?query=...` 查询/订阅	六
`systemctl`	deb 托管（SysV 生成单元）	start/stop/restart/reload/is-active	七
`jps -v`	OpenJDK	验证 JVM 堆参数生效	七
`riemann-dash`	Ruby gem（官方仪表盘）	Web 展示（实测不可用，见排障实录）	八

⚠️ 注意：Riemann 本体没有类似 redis-cli 的统一管理命令——摄入与查询都走「protobuf 客户端（riemann-client）或 HTTP/SSE 接口」两条路；apt 仓库也不提供 riemann-dash（只有 riemann-c-client、ruby-riemann-client、libriemann-client0、python3-bernhard、syslog-ng-mod-riemann 等客户端生态包），dash 需 gem 安装且见第八章结论。

三、前置条件

systemctl is-active riemann

active

C 客户端为独立 apt 包（本环境实测版本 1.10.4），未装时先安装：

apt-get install -y riemann-c-client
dpkg -S /usr/bin/riemann-client

riemann-c-client: /usr/bin/riemann-client

四、riemann launcher

/usr/bin/riemann 是 bash 启动器，末行 exec java $EXTRA_JAVA_OPTS $OPTS -cp "$JAR" riemann.bin "$COMMAND" "$CONFIG"，子命令透传给 riemann.bin。

4.1 riemann -v：版本查询

riemann -v 2>&1 | head -3

/usr/bin/riemann: line 11: [[: 11.032: syntax error: invalid arithmetic operator (error token is ".032")
WARNING: abs already refers to: #'clojure.core/abs in namespace: clojure.math.numeric-tower, being replaced by: #'clojure.math.numeric-tower/abs
0.3.12

解读：最后一行 0.3.12 是版本输出；首行报错是官方脚本第 11 行对四段 Java 版本号（11.0.32.1）解析缺陷（提取出 11.032 做算术比较失败），无害噪音，两分支都不执行、不影响启动；WARNING: abs 是 Clojure 库加载噪音。追求干净可把第 11 行改为只取主版本号：

JAVA_VERSION=$(java -version 2>&1 | awk -F\" '/version/ {print $2}' | cut -d. -f1)

4.2 riemann test：配置校验（不抢端口）

riemann test /etc/riemann/riemann.config

/usr/bin/riemann: line 11: [[: 11.032: syntax error: invalid arithmetic operator (error token is ".032")
WARNING: abs already refers to: #'clojure.core/abs in namespace: clojure.math.numeric-tower, being replaced by: #'clojure.math.numeric-tower/abs
INFO [2026-11-01 10:31:06,286] main - riemann.bin - Loading /etc/riemann/riemann.config

Testing clojure.core

Ran 0 tests containing 0 assertions.
0 failures, 0 errors.

实测要点：test 模式加载配置求值并跑 riemann.test 用例，不占用监听端口——上面命令是在服务已 active 的情况下执行的，全程无端口冲突报错。生产用法：改完配置先 test 再 reload。

4.3 start：前台启动

riemann start /etc/riemann/riemann.config

前台求值配置并启动核心，日志打到 stdout，Ctrl-C 停止。服务器日常托管不用它（用第七章 systemctl），它适合调试与 standalone jar 场景（java -jar riemann-0.3.12-standalone.jar start <config>，见安装篇第五章）。

五、riemann-client（C 客户端 1.10.4）

5.1 子命令与参数速查

riemann-client 两个子命令：

riemann-client send [-h host] [-S service] [-s state] [-D description]
                    [-a key=value] [-t tag] [-i sint64] [-d double] [-f float]
                    [-L ttl] [-T|-U|-G] [-0] [HOST] [PORT]
riemann-client query QUERY [HOST] [PORT] [-j]

send：-h host、-S service、-s state、-D description、-a key=value 属性（可重复）、-t 标签（可重复）、-i sint64 指标、-d double 指标、-f float 指标、-L ttl 秒；协议开关 -T(TCP)/-U(UDP)/-G(TLS)；-0 从 stdin 读事件；
query：位置参数为查询 DSL 字符串，默认服务器 localhost 5555，-j 输出 JSON；
发送成功无任何输出，失败才报错——脚本里可直接以退出码判断。

5.2 send + query 实测（TCP）

riemann-client send -h d1-web1 -S d1-test -s ok -d 3.14 -t d1 localhost 5555
riemann-client query 'service = "d1-test"' localhost 5555 -j

[{"time":1793529011,"time_micros":1793529011652000,"state":"ok","service":"d1-test","host":"d1-web1","ttl":60.0,"metric_d":3.1400000000000001,"metric_f":3.1400001049041748,"tags":["c1","d1"],"attributes":{"x-client":"riemann-c-client"}}]

解读三处实测细节：① -d 3.14 同时落成 metric_d（double 原值）与 metric_f（float 精度 3.1400001049041748）两形态；② 事件带上了 c1 标签——生产配置主链 (tag "c1" index) 对所有入流打标（配置详解篇 6.8），d1 是命令行 -t 加的；③ attributes.x-client=riemann-c-client 是客户端自报身份。

5.3 send（UDP）与多查询

riemann-client send -U -h d1-web2 -S d1-udp -s ok -i 7 localhost 5555
riemann-client query 'tagged "d1"' localhost 5555 -j

[{"time":1793529011,"time_micros":1793529011652000,"state":"ok","service":"d1-test","host":"d1-web1","ttl":60.0,"metric_d":3.1400000000000001,"metric_f":3.1400001049041748,"tags":["c1","d1"],"attributes":{"x-client":"riemann-c-client"}}]

tagged "d1" 只命中 5.2 的事件（UDP 事件未带 d1 标签）。用 or 查询把 TCP/UDP 两条都捞出来：

riemann-client query 'service = "d1-test" or service = "d1-udp"' localhost 5555 -j

[{"time":1793529011,"time_micros":1793529011652000,"state":"ok","service":"d1-test","host":"d1-web1","ttl":60.0,"metric_d":3.1400000000000001,"metric_f":3.1400001049041748,"tags":["c1","d1"],"attributes":{"x-client":"riemann-c-client"}},
{"time":1793529011,"time_micros":1793529011678000,"state":"ok","service":"d1-udp","host":"d1-web2","ttl":60.0,"metric_sint64":7,"metric_f":7.0,"tags":["c1"],"attributes":{"x-client":"riemann-c-client"}}]

UDP 事件 -i 7 落成 metric_sint64（整型指标）+ metric_f（float 镜像）。UDP 无回执、不保证送达，关键事件走 TCP。

5.4 query 默认 text 格式

不带 -j 时输出人类可读的逐字段格式：

riemann-client query 'service = "d1-test"' localhost 5555

Event #0:
  time  = 1793529011 - Sun Nov  1 10:30:11 2026
  state = ok
  service = d1-test

六、HTTP 与 SSE 接口

6.1 POST /events（5556，NDJSON 注入）

echo '{"host":"d1-web3","service":"d1-http","state":"warning","metric":1.5,"ttl":120}' | \
  curl -s -X POST --data-binary @- http://127.0.0.1:5556/events

{}

{} 为摄入回执；每行一个 JSON 对象（NDJSON），不是 JSON 数组——数组体会返回 class clojure.lang.LazySeq cannot be cast to class clojure.lang.Associative 错误（安装篇 FAQ 有完整实录）。

6.2 GET /index（5557，SSE 查询）

curl -s --max-time 2 "http://127.0.0.1:5557/index?query=service%20%3D%20%22d1-http%22"

data: {"host":"d1-web3","service":"d1-http","state":"warning","metric":1.5,"ttl":120,"time":"2026-11-01T10:30:11.707Z","tags":["c1"]}

SSE 是订阅流：命中当前索引的存量事件先逐条下发，此后匹配事件到达即推送；--max-time 2 取快照后断开。URL 中查询串需编码（=→%3D、"→%22、空格→%20）。

6.3 查询 DSL 操作符实测

操作符	含义	实测语句
`=`	等值（两侧必须空格、值用双引号）	`service = "cpu"`
`=~`	like（子串匹配）	`service =~ "cpu"`
`~=`	正则	`service ~= "^cpu$"`
`and` / `or` / `not`	布尔组合	`host = "web1" and not tagged "top"`
`tagged`	标签谓词	`tagged "c1"`

like 与正则两形态对同一事件均命中（等值 = 的命中见 6.2；生产配置下 cpu 事件被 rate 流覆盖，metric 为速率值）：

curl -s --max-time 2 "http://127.0.0.1:5557/index?query=service%20%3D~%20%22cpu%22"
curl -s --max-time 2 "http://127.0.0.1:5557/index?query=service%20~%3D%20%22%5Ecpu%24%22"

data: {"host":"web1","service":"cpu","state":"critical","metric":0,"time":"2026-11-01T10:28:15.438Z"}
data: {"host":"web1","service":"cpu","state":"critical","metric":0,"time":"2026-11-01T10:28:15.438Z"}

标签与组合谓词实测——tagged "c1" 命中面很宽（含 instrumentation 自监控事件，节选前 3 条）：

curl -s --max-time 2 "http://127.0.0.1:5557/index?query=tagged%20%22c1%22" | head -3

data: {"host":"riemann-srv","service":"riemann server udp 0.0.0.0:5555 in latency 0.95","state":"ok","description":null,"metric":null,"tags":["c1","riemann"],"time":"2026-11-01T10:28:10.421Z","ttl":20}
data: {"host":"riemann-srv","service":"riemann server tcp 0.0.0.0:2003 conns","state":"ok","description":null,"metric":1,"tags":["c1","riemann"],"time":"2026-11-01T10:28:10.421Z","ttl":20}
data: {"host":"riemann-srv","service":"riemann streams latency 0.99","state":null,"description":null,"metric":0.6470349999999999,"tags":["c1","riemann"],"time":"2026-11-01T10:28:10.420Z","ttl":20}

反例实测（两个「查不到」的常见原因）：

curl -s --max-time 2 "http://127.0.0.1:5557/index?query=host%20%3D%20%22localhost%22%20and%20service%20%3D%20%22riemann%20streams%20rate%22"
curl -s --max-time 2 "http://127.0.0.1:5557/index?query=host%20%3D%20%22ranker%22%20and%20not%20tagged%20%22top%22"

（两条查询均无输出）

原因分别为：instrumentation 事件 host 是服务器主机名 riemann-srv 而非 localhost（配置详解篇 5.7）；ranker 事件 ttl 60 已过期被清扫（配置详解篇 8.1）。服务端日志可佐证订阅解析：New SSE subscription to index for: host = "ranker" and not tagged "top" → Closing SSE channel 127.0.0.1 ...。

七、服务管理与 JVM 验证

7.1 systemctl 生命周期

systemctl restart riemann
systemctl is-active riemann

active

systemctl reload riemann
tail -3 /var/log/riemann/riemann.log

INFO [2026-11-01 10:28:21,734] SIGHUP handler - riemann.bin - Caught SIGHUP, reloading
INFO [2026-11-01 10:28:21,735] SIGHUP handler - riemann.pubsub - Sweeping transient subscriptions.
INFO [2026-11-01 10:28:21,779] SIGHUP handler - riemann.core - Hyperspace core online

reload=发 SIGHUP 全量热加载（PID 不变、索引保留）；restart=整进程重启（索引清空重建）。

7.2 jps -v 验证 JVM 堆生效

jps -v | grep -v Jps

5529 bin -Xms256m -Xmx512m

systemctl restart riemann
sleep 3
jps -v | grep -v Jps

6989 bin -Xms256m -Xmx512m

重启前后 PID 由 5529 变为 6989，-Xms256m -Xmx512m（来自 /etc/default/riemann 的 EXTRA_JAVA_OPTS）持续生效——堆限 256–512MB 符合 JVM 组件硬性要求，修改位置与原理见安装篇 7.2。

7.3 rate 流对索引的覆盖（轮询实录）

配置含 (where (service "cpu") (by :host (rate 5 index))) 时，rate 事件与原始事件同 [host service] 键，索引内互相覆盖。向 web3 注入 3 条 cpu metric 10：

printf '{"host":"web3","service":"cpu","state":"ok","metric":10}\n{"host":"web3","service":"cpu","state":"ok","metric":10}\n{"host":"web3","service":"cpu","state":"ok","metric":10}\n' | \
  curl -s -X POST --data-binary @- http://127.0.0.1:5556/events

{}
{}
{}

随后每秒轮询一次、连续 8 次（查询命令同 6.2，query 为 host = "web3" and service = "cpu"，提取 metric 字段），实测返回序列：

"metric":10
"metric":10
"metric":6
"metric":6
"metric":6
"metric":0
"metric":0
"metric":0

解读：前 2 秒原始事件尚在（10）；rate 窗口聚合后 6.0 = 30/5（5 秒窗口内 metric 和 ÷ 窗口秒数）；窗口空转后归 0。做原始值查询时要么避开 rate 覆盖的键，要么给 rate 流换 service 名（如 (with :service "cpu rate" ...)）。

八、riemann-dash 排障实录（结论：Ubuntu 22.04 不可用）

官方 Web 仪表盘 riemann-dash 在 apt 仓库无包，需 gem 安装。完整排障过程如下。

8.1 安装：先缺 ruby-dev 报错，装依赖后成功

gem install riemann-dash --no-document

ffi-1.17.4 extconf failed（gem 原生扩展编译失败）

定位：ffi 原生扩展编译需要 Ruby 开发头文件，系统缺 ruby-dev。补装编译依赖后重试成功：

apt-get install -y ruby-dev build-essential
gem install riemann-dash --no-document

Successfully installed riemann-dash-0.2.14

（连带 sass-3.7.4、multi_json、erubis 等共 8 个 gem。）

8.2 配置与启动

mkdir -p /etc/riemann-dash
cat > /etc/riemann-dash/config.rb <<'EOF'
set :port 4567
set :bind "0.0.0.0"
set :riemann_config "/etc/riemann/riemann.config"
set :riemann_url "tcp://127.0.0.1:5555"
EOF
riemann-dash /etc/riemann-dash/config.rb

[2026-11-01 10:32:07] INFO  WEBrick 1.3.1
[2026-11-01 10:32:07] INFO  ruby 3.0.2 (2021-07-07) [x86_64-linux-gnu]
== Sinatra (v1.4.8) has taken the stage on 4567 for development with backup from WEBrick
[2026-11-01 10:32:07] INFO  WEBrick::HTTPServer#start: pid=11498 port=4567

进程正常监听 4567。

8.3 访问 500 与根因定位

curl -s -o /dev/null -w "http_code=%{http_code}\n" http://127.0.0.1:4567/

http_code=500

日志根因：

Errno::ENOENT - No such file or directory @ rb_sysopen - .../riemann-dash-0.2.14/lib/riemann/dash/views/index.erb:

检查 gem 内 views 目录实际内容：

ls "$(gem environment gemdir)/gems/riemann-dash-0.2.14/lib/riemann/dash/views/"

css.scss  index.erubis  layout.erubis

根因：模板文件是 .erubis 扩展名，而 Sinatra 1.4.8 按 .erb 查找——0.2.14 gem 的打包/依赖失配（项目 2015 年后停更，Ubuntu 22.04 的 ruby 3.0.2 环境无匹配组合）。处置：kill ruby 进程，4567 释放。

⚠️ 结论：Ubuntu 22.04（ruby 3.0）上 riemann-dash 不可用。查询与展示改用内置通道：GET /index SSE（第六章）+ 自绘页面，或 Grafana 等第三方面板经 HTTP 数据源对接。

九、注意事项

NDJSON 不是 JSON 数组：POST /events 每行一个对象；数组体报 LazySeq 类型转换错误。
查询 DSL 空格敏感：= 两侧必须有空格（service="cpu" 会被整体吞成字段名报语法错）；字符串值必须双引号（service = cpu 恒不匹配）。
riemann-client 默认连 localhost 5555：远程服务器要显式传 HOST PORT 位置参数。
UDP 发送无回执：send -U 退出码 0 不代表送达；关键事件用 TCP。
索引只存最新态：查询为空先想 ttl 过期（默认 60 秒），不是丢数据。
rate 覆盖同键事件：见 7.3，原始 metric 与 rate 值共用索引键。
launcher line 11 报错是官方脚本缺陷：无害噪音，按 4.1 修复或忽略。
示例凭据说明：Riemann 本体无 Web 登录体系；dash 实测不可用，故本文不涉及管理账号。

十、常见问题（FAQ）

10.1 riemann-client: command not found？

Q： deb 装完 Riemann 后没有 riemann-client？ A：它是独立 apt 包：apt-get install -y riemann-c-client（1.10.4）。dpkg -S /usr/bin/riemann-client 可核对归属。

10.2 send 之后什么都没输出，成功了吗？

Q： riemann-client send ... 无任何回显？ A：是——send 成功即静默，用后续 query 验证（实测见 5.2）。脚本中按退出码判断。

10.3 query 返回 `[]` 或 SSE 无输出？

Q：刚发的事件查不到？ A：依次核对：① 查询语法空格/双引号（注意事项 2）；② 事件 ttl 是否已过期（默认 60 秒）；③ host 过滤值——instrumentation 事件 host 是服务器主机名不是 localhost（6.3 反例）；④ 是否被 rate 流覆盖键值（7.3）。

10.4 想要 Web 仪表盘？

Q： riemann-dash 起来就 500？ A： 0.2.14 gem 在 ruby 3.0 + Sinatra 1.4.8 下模板扩展名失配（第八章实录），无可靠修复路径。用 5557 SSE 接口自建页面或对接第三方面板。

10.5 `riemann test` 会不会影响在线服务？

Q：服务运行中执行 test 安全吗？ A：安全——test 模式不抢端口、不发布事件，仅求值配置跑用例（4.2 实测与服务并存）。

十一、参考链接

riemann-c-client（C 客户端/CLI）：https://github.com/riemann/riemann-c-client
Riemann 官方仓库：https://github.com/riemann/riemann
Riemann 官方文档：https://riemann.io/
Riemann Dash 仓库（停更背景）：https://github.com/riemann/riemann-dash
安装与 systemd/JVM 托管：《Ubuntu 22.04 安装 Riemann 0.3.12 指南》
配置参数与组合器语义：《Riemann 0.3.12 配置参数详解》
选型背景：《Riemann 介绍与选型指南》

Riemann 0.3.12 常用 CLI 命令与工具详解

Riemann 0.3.12 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、riemann launcher

4.1 riemann -v：版本查询

4.2 riemann test：配置校验（不抢端口）

4.3 start：前台启动

五、riemann-client（C 客户端 1.10.4）

5.1 子命令与参数速查

5.2 send + query 实测（TCP）

5.3 send（UDP）与多查询

5.4 query 默认 text 格式

六、HTTP 与 SSE 接口

6.1 POST /events（5556，NDJSON 注入）

6.2 GET /index（5557，SSE 查询）

6.3 查询 DSL 操作符实测

七、服务管理与 JVM 验证

7.1 systemctl 生命周期

7.2 jps -v 验证 JVM 堆生效

7.3 rate 流对索引的覆盖（轮询实录）

八、riemann-dash 排障实录（结论：Ubuntu 22.04 不可用）

8.1 安装：先缺 ruby-dev 报错，装依赖后成功

8.2 配置与启动

8.3 访问 500 与根因定位

九、注意事项

十、常见问题（FAQ）

10.1 riemann-client: command not found？

10.2 send 之后什么都没输出，成功了吗？

10.3 query 返回 [] 或 SSE 无输出？

10.4 想要 Web 仪表盘？

10.5 riemann test 会不会影响在线服务？

十一、参考链接

10.3 query 返回 `[]` 或 SSE 无输出？

10.5 `riemann test` 会不会影响在线服务？