Apache Samza 1.8.0 常用 CLI 命令与工具详解

目标：汇总 Apache Samza 1.8.0 部署骨架（samza-shell）自带脚本与配套 Kafka/YARN 工具的常用命令、参数与真实回显，覆盖作业提交、状态查询、终止、配置校验、检查点与状态存储管理，以及任务执行进程启动脚本。以下命令与回显均在 Ubuntu 22.04 真实环境逐步实测。

一、环境信息

项目	值
部署骨架目录	/opt/hello-samza/deploy/samza（bin/ 下为全部脚本）
提交端环境变量	`JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64`、`HADOOP_CONF_DIR=/opt/hadoop/etc/hadoop`
配套工具	Kafka 4.3.1（/opt/kafka/bin，需 JDK 17）、Hadoop 3.4.1（/opt/hadoop/bin）
日志目录	$SAMZA_LOG_DIR（默认为部署目录，含 stdout/stderr）

二、工具概览

工具	作用	等价命令
run-app.sh	提交/查询/终止 YARN 作业	yarn application -submit/-status/-kill
list-yarn-job.sh	列出运行中 Samza 作业	yarn application -list
stat-yarn-job.sh	查询单个作业详情	yarn application -status
kill-yarn-job.sh	终止作业	yarn application -kill
validate-yarn-job.sh	校验作业配置（YarnJobValidationTool）	—
checkpoint-tool.sh	查看/修改消费者检查点偏移（CheckpointTool）	—
state-storage-tool.sh	查看/清空任务状态存储（StateStorageTool）	—
read-rocksdb-tool.sh	读取 RocksDB 状态存储（RocksDbReadingTool）	—
run-container.sh	启动任务执行进程（SamzaContainer）	—
run-jc.sh	启动 JobCoordinator（YARN AM 入口）	—
run-class.sh	通用类启动器	java -cp <classpath> <class>
run-wikipedia-zk-application.sh	本地模式运行 Wikipedia 样例（ZkJobCoordinator）	—

三、前置条件

作业运行需要 ZooKeeper 与 Kafka（消息总线）；YARN 模式另需 Hadoop YARN 与 HADOOP_CONF_DIR（详见《Apache Samza 1.8.0 安装指南》）。
Kafka 4.x 工具命令需 JAVA_HOME 指向 OpenJDK 17；Samza 脚本需 OpenJDK 11。
环境准备（两段切换）：

# Samza 脚本用 JDK 11
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export HADOOP_CONF_DIR=/opt/hadoop/etc/hadoop

# Kafka 工具用 JDK 17
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:/opt/kafka/bin:$PATH

四、工具详解

4.1 run-app.sh（作业提交与运维）

提交作业：

cd /opt/hello-samza/deploy/samza
./bin/run-app.sh --config-path=config/wikipedia-parser.properties

真实回显（节选）：

2026-10-12 17:43:12.248 [main] JobPlanner [WARN] job.name is a deprecated configuration, use use app.name instead.
2026-10-12 17:43:12.384 [main] ClientHelper [INFO] trying to connect to RM localhost:8032
2026-10-12 17:43:12.893 [main] ClientHelper [INFO] preparing to request resources for app id application_1791822120187_0008
2026-10-12 17:43:13.001 [main] ClientHelper [INFO] set memory request to 512 for application_1791822120187_0008
2026-10-12 17:43:13.006 [main] ClientHelper [INFO] set cpu core request to 1 for application_1791822120187_0008
2026-10-12 17:43:13.056 [main] YarnClientImpl [INFO] Submitted application application_1791822120187_0008
2026-10-12 17:43:13.057 [main] JobRunner [INFO] Job submitted. Check status to determine when it is running.

参数说明（joptsimple 选项）：

--config-path：提交所用 properties 文件路径；
--operation：run / status / kill，默认 run；
无参运行报 ConfigException: Legacy task applications must set a non-empty task.class in configuration.；
--help 不受支持，报 joptsimple.UnrecognizedOptionException: help is not a recognized option。

4.2 list-yarn-job.sh（作业清单）

./bin/list-yarn-job.sh

真实回显：

Total number of applications (application-types: [] and states: [SUBMITTED, ACCEPTED, RUNNING]):2
                Application-Id      Application-Name        Application-Type          User           Queue                   State             Final-State             Progress                        Tracking-URL
application_1791822120187_0007    wikipedia-parser_1                   Samza          root      root.default              ACCEPTED               UNDEFINED                   0%                                 N/A
application_1791822120187_0006     wikipedia-stats_1                   Samza          root      root.default               RUNNING               UNDEFINED                   0%                  deaeeffa2c25:43141

⚠️ 必须设置 HADOOP_CONF_DIR=/opt/hadoop/etc/hadoop，否则脚本默认 $HOME/.samza/conf 不存在导致挂起/失败。

4.3 stat-yarn-job.sh（作业详情）

./bin/stat-yarn-job.sh application_1791822120187_0006

真实回显：

        User : root
        Queue : root.default
        Start-Time : 1791826148343
        Finish-Time : 0
        Progress : 0%
        State : RUNNING
        Final-State : UNDEFINED
        Tracking-URL : deaeeffa2c25:43141
        RPC Port : 38467
        AM Host : deaeeffa2c25
        Aggregate Resource Allocation : 649126 MB-seconds, 1267 vcore-seconds
        Diagnostics :

4.4 kill-yarn-job.sh（作业终止）

./bin/kill-yarn-job.sh application_1791822120187_0007

真实回显：

Killing application application_1791822120187_0007

⚠️ 直接接收 ApplicationId；传 --config-path= 会报 IllegalArgumentException: Invalid ApplicationId prefix。

4.5 validate-yarn-job.sh（配置校验）

./bin/validate-yarn-job.sh --config-path=config/wikipedia-parser.properties

无参报 ConfigException: Missing key job.config.loader.factory.（必须带 --config-path）；
校验通过则按 YarnJobValidationTool 输出校验结果，失败会给出缺失键。

4.6 checkpoint-tool.sh（消费者检查点）

./bin/checkpoint-tool.sh --config-path=config/wikipedia-parser.properties

查看/更新各系统分区消费偏移（--new-offsets 等选项）；
无参报 ConfigException: Missing key job.config.loader.factory.；
--help 不受支持，报 joptsimple.UnrecognizedOptionException: help is not a recognized option。

4.7 state-storage-tool.sh（状态存储管理）

./bin/state-storage-tool.sh --config-path=config/wikipedia-stats.properties

查看/清空任务状态存储（清空时校验作业已停止）；
无参报 ConfigException: Missing key job.config.loader.factory.。

4.8 read-rocksdb-tool.sh（RocksDB 存储读取）

./bin/read-rocksdb-tool.sh

无参报 joptsimple.UnrecognizedOptionException（需完整参数：作业配置、store 名称、key 等）；
用于线下核对 RocksDB 状态存储内容。

4.9 run-container.sh（任务执行进程启动）

./bin/run-container.sh --container-id <id> --coordinator-url <url>

直接运行报 Container ID: null / Coordinator URL: null / MalformedURLException（读取 JobModel 失败，必须传 --container-id 与 --coordinator-url，由框架内部调用，一般无需手工执行）；
用于排查任务执行进程独立启动问题。

4.10 run-jc.sh / run-class.sh（框架启动器）

./bin/run-jc.sh                 # YARN AM 入口，-Dsamza.container.name=samza-job-coordinator
./bin/run-class.sh <classname>  # 通用类启动器

run-jc.sh 无参即静默退出（需框架传入 coordinator 参数）；
run-class.sh org.apache.samza.util.CommandLine 报 Error: Main method not found（该类无 main）；
本地模式运行样例：./bin/run-wikipedia-zk-application.sh（入口 WikipediaZkLocalApplication，含 waitForFinish，进程保持存活）。

4.11 配套 Kafka 工具（JDK 17）

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:/opt/kafka/bin:$PATH

# 建 topic
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic wikipedia-raw --partitions 1 --replication-factor 1

# 列 topic
kafka-topics.sh --bootstrap-server localhost:9092 --list

# 查偏移量（Kafka 4.x 无 --describe）
kafka-get-offsets.sh --bootstrap-server localhost:9092 --topic wikipedia-stats
# wikipedia-stats:0:62

# 灌入数据
cat wikipedia-raw.json | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic wikipedia-raw

# 消费验证
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic wikipedia-edits --from-beginning --max-messages 2

消费回显（wikipedia-edits 样例记录，JSON 流）：

{"summary":"","diff-url":"http://en.wikipedia.org/w/index.php?diff=606586804&oldid=606586577","unparsed-flags":"M","flags":{"is-minor":true,"is-talk":false,"is-bot-edit":false,"is-new":false,"is-unpatched":true},"channel":"#en.wikipedia","namespace":"","user":"71.176.110.14","robot":false,"anonymous":true,"user-edit-count":0,"timestamp":"1392126026","page":"Linden Avenue Presbyterian Church","bytes-old":8807,"bytes-new":8856,"added":49,"deleted":0,"delta":49,"reverted":false}

4.12 配套 YARN 命令（JDK 11）

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:/opt/hadoop/bin:$PATH

yarn application -list
yarn application -status application_1791822120187_0006
yarn application -kill application_1791822120187_0007
yarn application -list -appStates ALL

五、注意事项

所有 samza-shell 脚本在 Java 11 下会输出 Unrecognized option: -d64、Unrecognized VM option 'PrintGCDateStamps'、-Xloggc is deprecated、[0.001s][warning][gc]: command not found 等探测噪音（run-class.sh 的 JVM 兼容性探测），不影响运行。
HADOOP_CONF_DIR 必须显式指向 /opt/hadoop/etc/hadoop，否则 YARN 相关脚本挂起或失败。
Kafka 4.x 工具需 OpenJDK 17；Samza 脚本需 OpenJDK 11，两个 JAVA_HOME 需按命令切换。
本地模式（run-wikipedia-zk-application.sh / WikipediaZkLocalApplication）不依赖 YARN，但仍需 ZooKeeper 与 Kafka 可用。

六、常见问题

6.1 list-yarn-job.sh 挂起无输出

定位：HADOOP_CONF_DIR 未设置，脚本指向不存在的 $HOME/.samza/conf。

解决：export HADOOP_CONF_DIR=/opt/hadoop/etc/hadoop 后重试。

6.2 run-app.sh 报 `ConfigException: Legacy task applications must set a non-empty task.class`

定位：未带 --config-path，properties 未加载。

解决：./bin/run-app.sh --config-path=config/wikipedia-parser.properties。

6.3 各工具报 `Missing key job.config.loader.factory.`

定位：validate/checkpoint/state-storage 等工具必须通过 --config-path 加载完整作业配置。

解决：补传 --config-path=config/<作业>.properties。

6.4 kill-yarn-job.sh 报 `IllegalArgumentException: Invalid ApplicationId prefix`

定位：错误传入 --config-path= 或非 AppId 参数。

解决：直接传 AppId：./bin/kill-yarn-job.sh application_1791822120187_0007。

七、参考链接

Samza 命令行工具文档：https://samza.apache.org/learn/documentation/latest/jobs/command-line.html
Samza 运维指南：https://samza.apache.org/learn/documentation/latest/operations/
Samza 检查点：https://samza.apache.org/learn/documentation/latest/checkpointing/checkpointing.html
Kafka 快速入门：https://kafka.apache.org/quickstart

Apache Samza 1.8.0 常用 CLI 命令与工具详解

Apache Samza 1.8.0 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、工具详解

4.1 run-app.sh（作业提交与运维）

4.2 list-yarn-job.sh（作业清单）

4.3 stat-yarn-job.sh（作业详情）

4.4 kill-yarn-job.sh（作业终止）

4.5 validate-yarn-job.sh（配置校验）

4.6 checkpoint-tool.sh（消费者检查点）

4.7 state-storage-tool.sh（状态存储管理）

4.8 read-rocksdb-tool.sh（RocksDB 存储读取）

4.9 run-container.sh（任务执行进程启动）

4.10 run-jc.sh / run-class.sh（框架启动器）

4.11 配套 Kafka 工具（JDK 17）

4.12 配套 YARN 命令（JDK 11）

五、注意事项

六、常见问题

6.1 list-yarn-job.sh 挂起无输出

6.2 run-app.sh 报 ConfigException: Legacy task applications must set a non-empty task.class

6.3 各工具报 Missing key job.config.loader.factory.

6.4 kill-yarn-job.sh 报 IllegalArgumentException: Invalid ApplicationId prefix

七、参考链接

6.2 run-app.sh 报 `ConfigException: Legacy task applications must set a non-empty task.class`

6.3 各工具报 `Missing key job.config.loader.factory.`

6.4 kill-yarn-job.sh 报 `IllegalArgumentException: Invalid ApplicationId prefix`