SeaTunnel Zeta 引擎 RESTful API V2 完全指南:监控、作业提交与集群运维
SeaTunnel Zeta 引擎 RESTful API V2 完全指南:监控、作业提交与集群运维
SeaTunnel(Zeta 引擎)内置了一套基于 HTTP 的监控与运维 API,可查询运行中作业与近期完成作业的状态和统计信息,也支持通过 JSON / HOCON / SQL 三种格式直接提交作业、停止作业、动态调整日志级别、查看集群资源快照等。本文以 docs/en/engines/zeta/rest-api-v2.md 为骨架,结合引擎源码(JettyService、ServerConfigOptions、REST Servlet 实现等)深入讲解 V2 API 的配置方式、全部端点语义、请求/响应格式与源码级实现原理,帮助读者在真实集群中完成 Web UI 开启、端口排障、作业生命周期管理、待调度作业诊断与 Checkpoint 观测。
V2 API 的适用前提与架构定位
SeaTunnel 的监控 API 是一套接受 HTTP 请求、以 JSON 响应的 RESTful API,由 SeaTunnel Engine(Zeta)服务端提供,因此它只对运行在 Zeta 引擎上的作业生效。当作业运行在 Flink 或 Spark 引擎上时,该 API 不可用,此时应使用对应引擎自带的提交与监控工具。
从源码结构看,V2 API 与 Web UI 均由内嵌 Jetty 服务承载,二者共用同一个 ServletContextHandler。JettyService 是这一切的入口,它在引擎启动时读取 SeaTunnelConfig 中的 HttpConfig,再逐一把 REST Servlet 注册到 Jetty 上。相关的核心文件包括:
- 服务端实现:JettyService.java
- 配置项定义:ServerConfigOptions.java
- 打包示例配置:seatunnel.yaml
Jetty 仅在 seatunnel.engine.http.enable-http = true 或 enable-https = true 时才会启动,这一点直接决定了 Web UI 与 REST API 的可用性。
HTTP 服务配置:两套“默认值”务必分清
使用 HTTP 服务前,首先要区分两套容易混淆的“默认值”:
| 来源 | 说明 |
|---|---|
| 代码默认值 | enable-http = false、enable-https = false、port = 8080、context-path = ""、enable-dynamic-port = false、port-range = 100、upload-max-file-size-mb = 10、upload-max-request-size-mb = 10 |
打包的 seatunnel.yaml 示例 |
已显式设置 enable-http: true 和 port: 8080 |
这两套默认值在 ServerConfigOptions.java 的 MasterServerConfigOptions 中有明确的源码定义:PORT 默认 8080、ENABLE_HTTP 默认 false、ENABLE_HTTPS 默认 false、CONTEXT_PATH 默认空串、ENABLE_DYNAMIC_PORT 默认 false、PORT_RANGE 默认 100、UPLOAD_MAX_FILE_SIZE_MB 与 UPLOAD_MAX_REQUEST_SIZE_MB 默认均为 10。
因此:
- 用打包配置启动 SeaTunnel 时,Web UI 和 REST API 通常监听在
http://<host>:8080/; - 自行编写最小配置、依赖代码默认值或删除了
enable-http时,Jetty 不会启动。
固定端口配置
seatunnel:
engine:
http:
enable-http: true
port: 8080
动态端口配置
若希望 Jetty 在 port 到 port + port-range 之间自动选择第一个空闲端口,需显式开启动态端口:
seatunnel:
engine:
http:
enable-http: true
port: 8080
enable-dynamic-port: true
port-range: 100
源码层面,JettyService 构造时若 isEnableDynamicPort() 为真,会调用 chooseAppropriatePort(port, portRange):从初始端口开始依次用 ServerSocket/DatagramSocket 探测占用情况,找到第一个空闲端口;若整个区间都被占用,则抛出 RuntimeException("Jetty failed to start, No available port found in the range!")(见 JettyService.java)。
context-path 配置
context-path 会让 Web UI 与全部 REST 端点统一挂到指定前缀下:
seatunnel:
engine:
http:
enable-http: true
port: 8080
context-path: /seatunnel
设置后,例如 overview 端点会变为 /seatunnel/overview。源码中 context.setContextPath(...) 读取该配置作为 Jetty 的上下文路径(见 JettyService.java)。
上传大小限制
上传配置文件的大小是有上限的,目的是防止单个请求占满 master 临时目录或耗尽堆内存。upload-max-file-size-mb 与 upload-max-request-size-mb 仅作用于 /submit-job/upload 端点,取值 0 或负数表示不限制:
seatunnel:
engine:
http:
enable-http: true
port: 8080
upload-max-file-size-mb: 10
upload-max-request-size-mb: 10
实现上,JettyService 将这两个 MB 值通过 toBytes() 换算为字节(megabytes <= 0 时返回 -1L,Jetty 将负数视为无限),再构造 MultipartConfigElement("", maxFileSize, maxRequestSize, 0) 绑定到上传 Servlet 上(见 JettyService.java)。
Web UI 与 8080 端口排障
- 若
http://<host>:8080/无法访问,首先确认seatunnel.engine.http.enable-http或enable-https是否真的开启。hazelcast.yaml中的network.rest-api.enabled不能替代 Jetty 开关。 - 若
enable-dynamic-port = true,实际监听端口可能不是 8080。Jetty 会在port到port + port-range之间选择第一个可用端口,以启动日志SeaTunnel REST service will start on port xxx为准。该日志由 JettyService.java 输出。 - 若
context-path = /seatunnel,Web UI 与 REST 端点都会移到该前缀下,例如 overview 端点变成/seatunnel/overview。 - Web UI 静态资源与 REST 端点共享同一个 Jetty 服务:Jetty 未启动时两者同时不可用。
启用 HTTPS
HTTPS 的配置请参考 security.md。从源码看,JettyService.enableHttps() 支持配置 https-port(默认 8443)、key-store-path、key-store-password、key-manager-password,以及可选的 trust-store-path/trust-store-password(配置后开启双向认证 setNeedClientAuth(true),见 JettyService.java)。
API 参考
以下端点均以 http://<host>:8080 为基址(按实际配置的端口与 context-path 调整)。
获取连接器 Option 规则(Get Connector Option Rules)
GET /option-rules?type=source&plugin=FakeSource
返回某个连接器的完整运行时 OptionRule 元数据。
参数
| name | type | data type | description |
|---|---|---|---|
| type | required | string | 插件类型,支持 source、sink、transform |
| plugin | required | string | 连接器工厂标识,例如 FakeSource 或 Console |
响应示例
{
"engineType": "seatunnel",
"pluginType": "source",
"pluginName": "FakeSource",
"optionRule": {
"optionalOptions": [
{
"key": "row.num",
"type": "java.lang.Integer",
"defaultValue": 5,
"description": "The total number of data generated per degree of parallelism",
"fallbackKeys": [],
"optionValues": null
}
],
"requiredOptions": [
{
"ruleType": "EXCLUSIVE",
"options": [
{
"key": "schema",
"type": "org.apache.seatunnel.api.table.catalog.TableSchema",
"defaultValue": null,
"description": "The schema of the upstream table",
"fallbackKeys": [],
"optionValues": null
}
]
},
{
"ruleType": "CONDITIONAL",
"options": [
{
"key": "string.template",
"type": "java.util.List<java.lang.String>",
"defaultValue": null,
"description": "The template list of string type that connector generated, if user configured it, connector will randomly select an item from the template list",
"fallbackKeys": [],
"optionValues": null
}
],
"expression": "'string.fake.mode' == TEMPLATE",
"expressionTree": {
"condition": {
"option": {
"key": "string.fake.mode",
"type": "org.apache.seatunnel.connectors.seatunnel.fake.config.FakeSourceOptions$FakeMode",
"defaultValue": "RANDOM",
"description": "The fake mode of generating string data",
"fallbackKeys": [],
"optionValues": [
"RANDOM",
"TEMPLATE"
]
},
"expectValue": "TEMPLATE",
"compareOperator": null,
"compareOption": null,
"conditionOperator": "EQUAL",
"conditionOperatorCategory": "EQUALITY",
"operator": null,
"next": null
},
"operator": null,
"next": null
}
}
],
"conditionRules": [],
"valueConstraints": [
{
"expression": "'row.num' >= 1",
"conditionTree": {
"option": {
"key": "row.num",
"type": "java.lang.Integer",
"defaultValue": 5,
"description": "The total number of data generated per degree of parallelism",
"fallbackKeys": [],
"optionValues": null
},
"expectValue": 1,
"compareOperator": ">=",
"compareOption": null,
"conditionOperator": "GREATER_OR_EQUAL",
"conditionOperatorCategory": "NUMERIC",
"operator": null,
"next": null
}
},
{
"expression": "'port' must be between 1 and 65535",
"conditionTree": {
"option": {
"key": "port",
"type": "java.lang.Integer",
"defaultValue": null,
"description": "Server port",
"fallbackKeys": [],
"optionValues": null
},
"expectValue": "must be between 1 and 65535",
"compareOperator": "extension",
"compareOption": null,
"conditionOperator": "EXTENSION",
"conditionOperatorCategory": "EXTENSION",
"operator": null,
"next": null
}
}
]
}
}
要点
- 响应来自运行时插件发现,因此跟随服务端实际安装的连接器版本变化。
requiredOptions[].ruleType可取ABSOLUTELY_REQUIRED、EXCLUSIVE、BUNDLED或CONDITIONAL。optionRule.conditionRules递归暴露嵌套的条件选项规则;连接器未定义嵌套规则时为空数组。- 条件规则会同时返回
expression与expressionTree,供动态表单渲染使用。 optionRule.valueConstraints描述值级校验规则(数值区间、字符串模式、跨字段比较等),每条提供人类可读的expression字符串与结构化conditionTree;连接器未定义约束时为空数组。conditionTree内:compareOperator在EQUAL时为null,否则为运行时规则暴露的操作符符号(如>=、is not blank、extension);compareOption仅跨字段比较时填充。conditionOperator是稳定的操作符标识,可能值包括EQUAL、GREATER_OR_EQUAL、NOT_BLANK、FIELD_LESS_THAN、EXTENSION等;conditionOperatorCategory表示操作符类别,如NUMERIC、STRING、COLLECTION、EQUALITY、EXTENSION等。- 对
EXTENSION条件,expectValue携带ConditionExtension.description()返回的规则描述文本。
源码层面,该端点由 OptionRulesServlet.java 处理:参数非法返回 400,插件不存在返回 404,加载失败返回 500,响应体统一为 {"status": "FAIL", "message": "..."} 形式的错误结构。
集群概览(Overview)
GET /overview?tag1=value1&tag2=value2
返回 Zeta 引擎集群的概览信息。
参数
| name | type | data type | description |
|---|---|---|---|
| tag_name | optional | string | 标签过滤,可过滤出匹配的 worker 数量及其上的 slot |
响应示例
{
"projectVersion":"2.3.10-SNAPSHOT",
"gitCommitAbbrev":"DeadD0d0",
"totalSlot":"0",
"unassignedSlot":"0",
"works":"1",
"runningJobs":"0",
"pendingJobs":"0",
"finishedJobs":"0",
"failedJobs":"0",
"cancelledJobs":"0"
}
要点
- 使用
dynamic-slot时,totalSlot与unassignedSlot恒为0;设置为固定 slot 数时返回正确的总数与未分配数。 - 若 URL 带标签过滤,
works、totalSlot、unassignedSlot返回匹配 worker 上的结果,但作业相关指标始终返回集群级信息。
查询 Worker 资源(Query Worker Resources)
GET /resource/workers
返回已注册 worker 的当前资源快照。
参数:无。
响应示例
{
"available": true,
"collectedAt": 1723017600000,
"workers": [
{
"address": "10.0.0.8:5801",
"tags": {"region": "us-west"},
"totalSlots": 4,
"freeSlots": 1,
"usedSlots": 3,
"dynamicSlot": false,
"totalCpuCores": 8,
"availableCpuCores": 2,
"totalHeapMemoryBytes": 17179869184,
"availableHeapMemoryBytes": 4294967296,
"cpuUsage": 0.42,
"memUsage": 0.58,
"runningJobIds": [123456789]
},
{
"address": "10.0.0.9:5801",
"tags": {},
"totalSlots": 2,
"freeSlots": 0,
"usedSlots": 2,
"dynamicSlot": true,
"totalCpuCores": 8,
"availableCpuCores": 4,
"totalHeapMemoryBytes": 17179869184,
"availableHeapMemoryBytes": 8589934592,
"cpuUsage": 0.35,
"memUsage": 0.41,
"runningJobIds": [123456789]
}
]
}
要点
- 固定 slot 的 worker 返回
totalSlots、usedSlots、freeSlots。 - 动态 slot 的 worker 没有固定容量:其
totalSlots表示当前追踪的已分配与未分配 slot 之和,freeSlots表示当前未分配数。解读容量时应结合dynamicSlot与 CPU、堆字段。 available在 master 资源快照不可读时为false(包括 master 选举窗口期),此时workers为空,客户端应重试而非将其理解为空集群。collectedAt是 master 构建该响应的时间戳(毫秒)。worker 数值来自最近的资源管理器心跳,并非与/system-monitoring-information的原子采样。- 资源与使用率字段在 worker 心跳尚未携带对应值时会被省略。
运行中作业概览与状态(Query An Overview And State Of Running Jobs)
GET /running-jobs?page=1&rows=10
参数
| name | type | data type | description |
|---|---|---|---|
| page | optional | int | 页码 |
| rows | optional | int | 每页条数 |
响应示例
[
{
"jobId": "",
"jobName": "",
"jobStatus": "",
"envOptions": {
},
"createTime": "",
"jobDag": {
"jobId": "",
"envOptions": [],
"vertexInfoMap": [
{
"vertexId": 1,
"type": "",
"vertexName": "",
"tablePaths": [
""
]
}
],
"pipelineEdges": {}
},
"pluginJarsUrls": [
],
"isStartWithSavePoint": false,
"metrics": {
"sourceReceivedCount": "",
"sinkWriteCount": ""
}
}
]
待调度作业诊断(Returns Diagnostic Information For Pending Jobs)
GET /pending-jobs?jobId=123&limit=10
用于检查待调度队列、slot 使用情况与阻塞原因,是排查作业长时间停留在 PENDING 状态的核心工具。
参数
| name | type | data type | description |
|---|---|---|---|
| jobId | optional | long | 若设置,只返回指定作业的诊断信息。jobId 与 limit 同时提供时,jobId 优先,limit 被忽略 |
| limit | optional | integer | 限制返回的作业数量。提供 jobId 时被忽略 |
| pretty | optional | boolean | 为 true 时美化输出 JSON,并将时间戳字段格式化为可读时间 |
响应示例
{
"queueSummary": {
"size": 2,
"scheduleStrategy": "WAIT",
"oldestEnqueueTimestamp": 1717500000000,
"newestEnqueueTimestamp": 1717500005000,
"lackingTaskGroups": 6
},
"clusterSnapshot": {
"totalSlots": 8,
"freeSlots": 1,
"assignedSlots": 7,
"workerCount": 2,
"workers": [
{
"address": "10.0.0.8:5801",
"tags": {
"zone": "az1"
},
"totalSlots": 4,
"freeSlots": 0,
"usedSlots": 4,
"dynamicSlot": false,
"totalCpuCores": 8,
"availableCpuCores": 2,
"totalHeapMemoryBytes": 17179869184,
"availableHeapMemoryBytes": 4294967296,
"cpuUsage": 0.83,
"memUsage": 0.64,
"runningJobIds": [
1001,
1002
]
}
]
},
"pendingJobs": [
{
"jobId": 1003,
"jobName": "cdc_mysql_to_es",
"pendingSourceState": "SUBMIT",
"jobStatus": "PENDING",
"enqueueTimestamp": 1717500000000,
"checkTime": 1717500005000,
"waitDurationMs": 5000,
"checkCount": 3,
"totalTaskGroups": 16,
"allocatedTaskGroups": 10,
"lackingTaskGroups": 6,
"failureReason": "REQUEST_FAILED",
"failureMessage": "NoEnoughResourceException: can't apply resource request",
"tagFilter": {},
"blockingJobIds": [
1001
],
"pipelines": [
{
"pipelineId": 1,
"pipelineName": "Job job-name, Pipeline: [(1/2)]",
"totalTaskGroups": 8,
"allocatedTaskGroups": 5,
"lackingTaskGroups": 3,
"taskGroupDiagnostics": [
{
"taskGroupLocation": {
"jobId": 1003,
"pipelineId": 1,
"taskGroupId": 1
},
"taskFullName": "Source[0]",
"allocated": false,
"failureReason": "REQUEST_FAILED",
"failureMessage": "NoEnoughResourceException: slot not enough"
}
]
}
],
"lackingTaskGroupDiagnostics": [
{
"taskGroupLocation": {
"jobId": 1003,
"pipelineId": 1,
"taskGroupId": 1
},
"taskFullName": "Source[0]",
"allocated": false,
"failureReason": "REQUEST_FAILED",
"failureMessage": "NoEnoughResourceException: slot not enough"
}
]
}
]
}
当 pretty=true 时,端点返回美化后的 JSON,并把 oldestEnqueueTimestamp、newestEnqueueTimestamp、enqueueTimestamp、checkTime 格式化为 yyyy-MM-dd HH:mm:ss。
该端点通过展示待调度队列顺序、聚合资源视图与每个 TaskGroup 的 slot 请求失败原因(标签不匹配、worker 繁忙、资源耗尽等),帮助定位作业停留在 PENDING 的原因。
Pending Jobs 响应字段
- queueSummary —— 整个待调度队列的概览。
size:当前待调度作业数。scheduleStrategy:当前调度策略(如WAIT、FAIL_FAST),决定资源不足时的行为。oldestEnqueueTimestamp/newestEnqueueTimestamp:队列中最旧/最新作业的入队时间戳(ms)。lackingTaskGroups:仍在等待 slot 的 TaskGroup 总数。注意:该值只反映当前响应中包含的作业(即被limit截断或按jobId过滤后的子集),并非整个待调度队列的统计。要查看全部待调度作业的完整统计,需在调用时不带limit参数。
- clusterSnapshot —— 集群资源快照(可被标签过滤)。
totalSlots/assignedSlots/freeSlots:过滤视图下的总、已分配与剩余 slot。workerCount:匹配标签过滤的 worker 数量。workers[]:每个 worker 的详情。address:worker 的 host:port。tags:worker 级标签。totalSlots/freeSlots:该 worker 的 slot 容量与可用数量。dynamicSlot:该 worker 是否使用动态 slot 分配。cpuUsage/memUsage:采样系统负载(仅当slot-allocate-strategy为SYSTEM_LOAD时出现)。runningJobIds[]:当前占用该 worker slot 的作业(用于识别阻塞者)。
- pendingJobs[] —— 每个待调度作业的诊断。
jobId/jobName:作业标识。pendingSourceState:作业来自新提交(SUBMIT)还是 master 切换恢复(RESTORE)。jobStatus:物理计划中记录的作业状态(通常为PENDING)。enqueueTimestamp:作业进入待调度队列的时间。checkTime:最近一次诊断快照的时间戳。waitDurationMs:checkTime - enqueueTimestamp。checkCount:调度器检查该作业的次数。totalTaskGroups/allocatedTaskGroups/lackingTaskGroups:TaskGroup 总数/已分配/缺失数。failureReason/failureMessage:分类原因(如RESOURCE_NOT_ENOUGH、REQUEST_FAILED)及原始消息。tagFilter:作业声明的 worker 标签要求(若有)。blockingJobIds[]:当前占用所需 slot 的其他作业。pipelines[]:按 pipeline 拆分。pipelineId/pipelineName。totalTaskGroups/allocatedTaskGroups/lackingTaskGroups。taskGroupDiagnostics[](每个 TaskGroup 的 slot 请求状态):taskGroupLocation(jobId、pipelineId、taskGroupId)。taskFullName:可读名称(source/sink 等)。allocated:slot 请求是否成功。failureReason/failureMessage:分配失败时的任务级原因。
lackingTaskGroupDiagnostics[]:allocated=false的 TaskGroup 扁平列表,便于快速浏览。
作业详情(Return Details Of A Job)
GET /job-info/:jobId
参数
| name | type | data type | description |
|---|---|---|---|
| jobId | required | long | 作业 id |
响应示例
{
"jobId": "",
"jobName": "",
"jobStatus": "",
"createTime": "",
"jobDag": {
"jobId": "",
"envOptions": [],
"vertexInfoMap": [
{
"vertexId": 1,
"type": "",
"vertexName": "",
"tablePaths": [
""
]
}
],
"pipelineEdges": {}
},
"metrics": {
"IntermediateQueueSize": "",
"SourceReceivedCount": "",
"SourceReceivedQPS": "",
"SourceReceivedBytes": "",
"SourceReceivedBytesPerSeconds": "",
"SinkWriteCount": "",
"SinkWriteQPS": "",
"SinkWriteBytes": "",
"SinkWriteBytesPerSeconds": "",
"SinkCommittedCount": "",
"SinkCommittedQPS": "",
"SinkCommittedBytes": "",
"SinkCommittedBytesPerSeconds": "",
"TableSourceReceivedCount": {},
"TableSourceReceivedBytes": {},
"TableSourceReceivedBytesPerSeconds": {},
"TableSourceReceivedQPS": {},
"TableSinkWriteCount": {},
"TableSinkWriteQPS": {},
"TableSinkWriteBytes": {},
"TableSinkWriteBytesPerSeconds": {},
"TableSinkCommittedCount": {},
"TableSinkCommittedQPS": {},
"TableSinkCommittedBytes": {},
"TableSinkCommittedBytesPerSeconds": {}
},
"finishedTime": "",
"errorMsg": null,
"envOptions": {
},
"pluginJarsUrls": [
],
"isStartWithSavePoint": false,
"diagnostics": {
"jobId": "",
"generatedAt": 1755000004000,
"stateTimestamps": {
"INITIALIZING": 1755000000000,
"CREATED": 1755000000200,
"SCHEDULED": 1755000001000,
"RUNNING": 1755000003000
},
"pipelines": [
{
"pipelineId": 1,
"pipelineStatus": "RUNNING",
"restoreCount": 7,
"maxRestoreCount": 100,
"stateTimestamps": {
"INITIALIZING": 1755000000000,
"CREATED": 1755000000200,
"SCHEDULED": 1755000001100,
"DEPLOYING": 1755000002000,
"RUNNING": 1755000003500
}
}
],
"totalPipelineRestoreCount": 7
}
}
返回字段规则:
jobId、jobName、jobStatus、createTime、jobDag、metrics总是返回。envOptions、pluginJarsUrls、isStartWithSavePoint在作业运行时返回。finishedTime、errorMsg在作业结束时返回。diagnostics在作业运行且能从 master 节点读取诊断信息时返回。它是辅助信息:获取不到时该字段被省略而不会导致请求失败。只有该端点返回它;/running-jobs不返回,因为为每个运行中作业采集诊断需要每个作业向 master 多一次往返。
Metrics 字段说明
| Field | Description |
|---|---|
| IntermediateQueueSize | 算子间中间队列大小 |
| SourceReceivedCount | 从 source 接收的总行数 |
| SourceReceivedQPS | source 接收速率(行/秒) |
| SourceReceivedBytes | 从 source 接收的总字节数 |
| SourceReceivedBytesPerSeconds | source 接收速率(字节/秒) |
| SinkWriteCount | sink 写入尝试次数(行) |
| SinkWriteQPS | sink 写入尝试速率(行/秒) |
| SinkWriteBytes | sink 写入尝试字节数 |
| SinkWriteBytesPerSeconds | sink 写入尝试速率(字节/秒) |
| SinkCommittedCount | checkpoint 成功后 sink 提交的行数 |
| SinkCommittedQPS | sink 提交速率(行/秒) |
| SinkCommittedBytes | checkpoint 成功后 sink 提交的字节数 |
| SinkCommittedBytesPerSeconds | sink 提交速率(字节/秒) |
| TableSourceReceived* | 按表统计的 source 指标,key 格式 TableSourceReceivedXXX#<table> |
| TableSinkWrite* | 按表统计的 sink 写入尝试,key 格式 TableSinkWriteXXX#<table> |
| TableSinkCommitted* | 按表统计的 sink 提交指标,key 格式 TableSinkCommittedXXX#<table> |
Diagnostics 字段说明
| Field | Description |
|---|---|
| generatedAt | 采集该诊断块时的 epoch 毫秒时间 |
| stateTimestamps | 作业进入各状态时的 epoch 毫秒时间。从未进入的状态被省略。pipeline 重启不改变作业状态,因此仅凭该字段无法看出重启 |
| pipelines[].pipelineId | 作业内的 pipeline id |
| pipelines[].pipelineStatus | 当前 pipeline 状态 |
| pipelines[].restoreCount | 自作业提交以来该 pipeline 被恢复的次数。jobStatus 保持 RUNNING 而该值持续增长,说明处于崩溃循环 |
| pipelines[].maxRestoreCount | 该 pipeline 的恢复上限,来自 job.retry.times env 选项 |
| pipelines[].stateTimestamps | pipeline 进入各状态的 epoch 毫秒时间。恢复后,新尝试的时间戳覆盖旧值 |
| totalPipelineRestoreCount | 作业所有 pipeline 的 restoreCount 之和 |
当无法获取作业信息时,响应为:
{
"jobId" : ""
}
已弃用:运行中作业详情(Return Details Of A Job)
GET /running-job/:jobId
该 API 已弃用,请改用 /job-info/:jobId。 参数与响应结构与 /job-info/:jobId 基本一致(但不含 diagnostics 字段):
jobId、jobName、jobStatus、createTime、jobDag、metrics总是返回。envOptions、pluginJarsUrls、isStartWithSavePoint在作业运行时返回。finishedTime、errorMsg在作业结束时返回。
无法获取作业信息时同样返回 {"jobId": ""}。
查询已完成作业(Query Finished Jobs Info)
GET /finished-jobs/:state?page=1&rows=10
参数
| name | type | data type | description |
|---|---|---|---|
| state | optional | string | 已完成作业状态:FINISHED、CANCELED、FAILED、SAVEPOINT_DONE、UNKNOWABLE |
| page | optional | int | 页码,必须为大于 0 的整数 |
| rows | optional | int | 每页条数,默认 10,必须为大于 0 的整数 |
分页规则:
- 提供
page时,响应包装为{"data": [...], "total": n},其中total是应用分页前匹配state的作业数;省略page时返回裸数组。 page或rows不是整数或不大于 0 时返回400。页码超过结果集末尾也返回400,而页码恰好等于total时返回空页。
响应示例
[
{
"jobId": "",
"jobName": "",
"jobStatus": "",
"errorMsg": null,
"createTime": "",
"finishTime": "",
"jobDag": {
"jobId": "",
"envOptions": [],
"vertexInfoMap": [
{
"vertexId": 1,
"type": "",
"vertexName": "",
"tablePaths": [
""
]
}
],
"pipelineEdges": {}
},
"metrics": ""
}
]
系统监控信息(Returns System Monitoring Information)
GET /system-monitoring-information
参数:无。
响应示例
[
{
"processors":"8",
"physical.memory.total":"16.0G",
"physical.memory.free":"16.3M",
"swap.space.total":"0",
"swap.space.free":"0",
"heap.memory.used":"135.7M",
"heap.memory.free":"440.8M",
"heap.memory.total":"576.5M",
"heap.memory.max":"3.6G",
"heap.memory.used/total":"23.54%",
"heap.memory.used/max":"3.73%",
"minor.gc.count":"6",
"minor.gc.time":"110ms",
"major.gc.count":"2",
"major.gc.time":"73ms",
"load.process":"24.78%",
"load.system":"60.00%",
"load.systemAverage":"2.07",
"thread.count":"117",
"thread.peakCount":"118",
"cluster.timeDiff":"0",
"event.q.size":"0",
"executor.q.async.size":"0",
"executor.q.client.size":"0",
"executor.q.client.query.size":"0",
"executor.q.client.blocking.size":"0",
"executor.q.query.size":"0",
"executor.q.scheduled.size":"0",
"executor.q.io.size":"0",
"executor.q.system.size":"0",
"executor.q.operations.size":"0",
"executor.q.priorityOperation.size":"0",
"operations.completed.count":"10",
"executor.q.mapLoad.size":"0",
"executor.q.mapLoadAllKeys.size":"0",
"executor.q.cluster.size":"0",
"executor.q.response.size":"0",
"operations.running.count":"0",
"operations.pending.invocations.percentage":"0.00%",
"operations.pending.invocations.count":"0",
"proxy.count":"8",
"clientEndpoint.count":"0",
"connection.active.count":"2",
"client.connection.count":"0",
"connection.count":"0"
}
]
提交作业(Submit A Job)
POST /submit-job
成功提交后返回 jobId 和 jobName。
参数
| name | type | data type | description |
|---|---|---|---|
| jobId | optional | string | 作业 id |
| jobName | optional | string | 作业名 |
| isStartWithSavePoint | optional | string | 作业是否从 savepoint 启动 |
| restoreMode | optional | string | 作业恢复来源:CHECKPOINT 或 SAVEPOINT。与 restoreSourceJobId 配合使用,见 rest-api-job-lifecycle.md#6-job-recovery-and-restart |
| restoreSourceJobId | optional | string | 设置 restoreMode 时指定要恢复的作业 id;仅设置 isStartWithSavePoint(无 restoreMode)时回退为 jobId |
| format | optional | string | 配置格式,支持 json、hocon 和 sql,默认 json |
注意:dry-run 特性刻意不支持通过 REST API 使用,仅可通过 SeaTunnel CLI 使用。从源码看,JobInfoService.submitJob() 在检测到 dry_run 参数时会直接抛出 IllegalArgumentException("Dry-run is only supported via CLI")(见 JobInfoService.java)。
请求体
可在请求体中选 JSON、HOCON 或 SQL 三种格式。
JSON 格式示例:
{
"env": {
"job.mode": "batch"
},
"source": [
{
"plugin_name": "FakeSource",
"plugin_output": "fake",
"row.num": 100,
"schema": {
"fields": {
"name": "string",
"age": "int",
"card": "int"
}
}
}
],
"transform": [
],
"sink": [
{
"plugin_name": "Console",
"plugin_input": ["fake"]
}
]
}
HOCON 格式示例:
env {
job.mode = "batch"
}
source {
FakeSource {
plugin_output = "fake"
row.num = 100
schema = {
fields {
name = "string"
age = "int"
card = "int"
}
}
}
}
transform {
}
sink {
Console {
plugin_input = "fake"
}
}
SQL 格式示例:
/* config
env {
parallelism = 2
job.mode = "BATCH"
}
*/
CREATE TABLE fake_source (
id INT,
name STRING,
age INT
) WITH (
'connector' = 'FakeSource',
'rows' = '[
{ fields = [1, "Alice", 25], kind = INSERT },
{ fields = [2, "Bob", 30], kind = INSERT }
]',
'schema' = '{
fields {
id = "int",
name = "string",
age = "int"
}
}',
'type' = 'source'
);
CREATE TABLE console_sink (
id INT,
name STRING,
age INT
) WITH (
'connector' = 'Console',
'type' = 'sink'
);
INSERT INTO console_sink SELECT * FROM fake_source;
响应示例
{
"jobId": 733584788375666689,
"jobName": "rest_api_test"
}
从源码看,SubmitJobServlet.doPost() 读取 format 参数(ConfigFormat.fromString),将请求体按 JSON / HOCON / SQL 分别解析为 SeaTunnel Config,随后经 ConfigShadeUtils.decryptConfig(config) 解密后提交(见 SubmitJobServlet.java 与 JobInfoService.java)。
通过上传配置文件提交作业(Submit A Job By Upload Config File)
POST /submit-job/upload
参数
| name | type | data type | description |
|---|---|---|---|
| jobId | optional | string | 作业 id |
| jobName | optional | string | 作业名 |
| isStartWithSavePoint | optional | string | 作业是否从 savepoint 启动 |
| restoreMode | optional | string | 作业恢复来源:CHECKPOINT 或 SAVEPOINT,与 restoreSourceJobId 配合使用,见 rest-api-job-lifecycle.md#6-job-recovery-and-restart |
| restoreSourceJobId | optional | string | 设置 restoreMode 时指定要恢复的作业 id;仅设置 isStartWithSavePoint(无 restoreMode)时回退为 jobId |
请求体
上传文件的表单字段名为 config_file,支持以下格式:
.json文件:按 JSON 格式解析.conf或.config文件:按 HOCON 格式解析.sql文件:按 SQL 格式解析,支持 CREATE TABLE 与 INSERT INTO 语法
上传受 seatunnel.engine.http.upload-max-file-size-mb(默认 10 MB,单文件)与 upload-max-request-size-mb(默认 10 MB,单请求)限制,超限的上传会在解析配置前被拒绝。
curl 示例:
# Upload HOCON config file
curl --location 'http://127.0.0.1:8080/submit-job/upload' --form 'config_file=@"/temp/fake_to_console.conf"'
# Upload SQL config file
curl --location 'http://127.0.0.1:8080/submit-job/upload' --form 'config_file=@"/temp/job.sql"'
# Upload a config file and restore from the latest checkpoint of a previous job
curl --location 'http://127.0.0.1:8080/submit-job/upload?restoreMode=CHECKPOINT&restoreSourceJobId=733584788375666689' --form 'config_file=@"/temp/fake_to_console.conf"'
响应示例
{
"jobId": 733584788375666689,
"jobName": "SeaTunnel_Job"
}
批量提交作业(Batch Submit Jobs)
POST /submit-jobs
成功提交后返回每个作业的 jobId 和 jobName。
参数(放在请求体的 params 字段中)
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| jobId | optional | string | 作业 id |
| jobName | optional | string | 作业名 |
| isStartWithSavePoint | optional | string | 作业是否从 savepoint 启动 |
请求体
[
{
"params":{
"jobId":"123456",
"jobName":"SeaTunnel-01"
},
"env": {
"job.mode": "batch"
},
"source": [
{
"plugin_name": "FakeSource",
"plugin_output": "fake",
"row.num": 1000,
"schema": {
"fields": {
"name": "string",
"age": "int",
"card": "int"
}
}
}
],
"transform": [
],
"sink": [
{
"plugin_name": "Console",
"plugin_input": ["fake"]
}
]
},
{
"params":{
"jobId":"1234567",
"jobName":"SeaTunnel-02"
},
"env": {
"job.mode": "batch"
},
"source": [
{
"plugin_name": "FakeSource",
"plugin_output": "fake",
"row.num": 1000,
"schema": {
"fields": {
"name": "string",
"age": "int",
"card": "int"
}
}
}
],
"transform": [
],
"sink": [
{
"plugin_name": "Console",
"plugin_input": ["fake"]
}
]
}
]
响应示例
[
{
"jobId": "123456",
"jobName": "SeaTunnel-01"
},{
"jobId": "1234567",
"jobName": "SeaTunnel-02"
}
]
停止作业(Stop A Job)
POST /stop-job
成功停止后返回 jobId。
参数
| name | required | data type | description |
|---|---|---|---|
| jobId | yes | long | 作业 id |
| isStopWithSavePoint | no | boolean | 作业是否带 savepoint 停止 |
| force | no | boolean | 为 true 时强制停止(忽略 isStopWithSavePoint) |
请求体
{
"jobId": 733584788375666689,
"isStopWithSavePoint": false,
"force": false
}
响应示例
{
"jobId": 733584788375666689
}
要点
- 若作业状态为
DOING_SAVEPOINT且 savepoint 未能成功完成,强制停止(启用force)会将作业状态置为CANCELED。 - 强制停止可能留下不完整或不一致的 checkpoint 数据,仅在异常场景下使用。
批量停止作业(Batch Stop Jobs)
POST /stop-jobs
请求体
[
{
"jobId": 881432421482889220,
"isStopWithSavePoint": false,
"force": false
},
{
"jobId": 881432456517910529,
"isStopWithSavePoint": false,
"force": false
}
]
响应示例
[
{
"jobId": 881432421482889220
},
{
"jobId": 881432456517910529
}
]
加密配置(Encrypt Config)
POST /encrypt-config
成功加密后返回加密后的配置。自定义加密的更多信息见 config-encryption-decryption。
请求体
{
"env": {
"parallelism": 1,
"shade.identifier":"base64"
},
"source": [
{
"plugin_name": "MySQL-CDC",
"schema" : {
"fields": {
"name": "string",
"age": "int"
}
},
"plugin_output": "fake",
"parallelism": 1,
"hostname": "127.0.0.1",
"username": "seatunnel",
"password": "seatunnel_password",
"table-name": "inventory_vwyw0n"
}
],
"transform": [
],
"sink": [
{
"plugin_name": "Clickhouse",
"host": "localhost:8123",
"database": "default",
"table": "fake_all",
"username": "seatunnel",
"password": "seatunnel_password"
}
]
}
响应示例
{
"env": {
"parallelism": 1,
"shade.identifier": "base64"
},
"source": [
{
"plugin_name": "MySQL-CDC",
"schema": {
"fields": {
"name": "string",
"age": "int"
}
},
"plugin_output": "fake",
"parallelism": 1,
"hostname": "127.0.0.1",
"username": "c2VhdHVubmVs",
"password": "c2VhdHVubmVsX3Bhc3N3b3Jk",
"table-name": "inventory_vwyw0n"
}
],
"transform": [],
"sink": [
{
"plugin_name": "Clickhouse",
"host": "localhost:8123",
"database": "default",
"table": "fake_all",
"username": "c2VhdHVubmVs",
"password": "c2VhdHVubmVsX3Bhc3N3b3Jk"
}
]
}
可见 username、password 等敏感字段被按 shade.identifier 指定的方式(示例中为 base64)加密替换。
更新运行节点标签(Update the tags of running node)
POST /update-tags
更新只能针对具体节点,因此需使用当前节点的 ip:port 发起请求。
更新节点标签
请求体为 Map 对象时表示更新当前节点的标签:
{
"tag1": "dev_1",
"tag2": "dev_2"
}
响应:
{
"status": "success",
"message": "update node tags done."
}
清除节点标签
请求体为空 Map 表示清除当前节点标签:
{}
响应同上。
请求参数异常
- 请求体为空:
{
"status": "fail",
"message": "Request body is empty."
}
- 请求体不是
Map对象:
{
"status": "fail",
"message": "Invalid JSON format in request body."
}
获取所有节点的日志(Get Logs from All Nodes)
GET /logs/:jobId
返回日志列表。参数 jobId 可放在请求体的 params 字段中:
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| jobId | optional | string | 作业 id |
jobId 为空时返回所有节点的日志;否则返回指定 jobId 在所有节点上的日志列表。
获取所有日志文件列表:可用 GET 请求 http://localhost:8080/logs?format=json 先查看日志列表:
[
{
"node": "localhost:8080",
"logLink": "http://localhost:8080/logs/job-899485770241277953.log",
"logName": "job-899485770241277953.log"
},
{
"node": "localhost:8080",
"logLink": "http://localhost:8080/logs/job-899470314109468673.log",
"logName": "job-899470314109468673.log"
}
]
支持的格式为 json 与 html,默认 html。
示例
- 获取
jobId为733584788375666689在所有节点的日志:http://localhost:8080/logs/733584788375666689 - 获取所有节点的日志列表:
http://localhost:8080/logs - 以 JSON 格式获取日志列表:
http://localhost:8080/logs?format=json - 获取某个日志文件内容:
http://localhost:8080/logs/job-898380162133917698.log
获取单个节点的日志内容(Get Log Content from a Single Node)
GET /log
返回请求节点的日志列表。
示例
- 获取当前节点的日志列表:
http://localhost:5801/log - 获取某个日志文件内容:
http://localhost:5801/log/job-898380162133917698.log
读取与修改日志级别(Read And Change Log Levels)
通过这些端点修改的日志级别是运行时覆盖:立即生效、仅节点本地、节点重启后丢失。需要在重启后保留的级别应写入 config/log4j2.properties,参见 logging.md。根 logger 以 root 指代。
列出日志器
GET /loggers
查询参数
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| scope | optional | string | node(默认)回答处理请求的节点,cluster 询问每个成员 |
响应示例
{
"node": "localhost:8080",
"loggers": [
{
"name": "root",
"level": "INFO",
"origin": "file"
},
{
"name": "org.apache.seatunnel.connectors.seatunnel.jdbc",
"level": "DEBUG",
"origin": "runtime-override",
"fileLevel": "INFO"
}
]
}
origin 说明当前级别来源:file 表示来自 log4j2 配置文件,runtime-override 表示通过日志级别端点设置。fileLevel 仅当被覆盖的 logger 也在文件中配置时出现,表示 DELETE 将恢复的级别。
?scope=cluster 时每个成员一个条目:
{
"scope": "cluster",
"status": "SUCCESS",
"nodes": [
{
"node": "localhost:8080",
"loggers": [
{
"name": "root",
"level": "INFO",
"origin": "file"
}
]
}
]
}
status 在所有成员应答时为 SUCCESS,部分成员未应答时为 PARTIAL_FAILURE,全部未应答时为 FAILURE;失败的成员携带自身的 status 与 error。集群请求按各成员配置中的 REST 端口访问每个成员,因此无法到达通过 enable-dynamic-port 使用了其他端口的成员。
查询单个日志器
GET /loggers/:name
返回指定 logger 的有效级别。级别通过最近的已配置祖先解析,因此即使某个 logger 自身未配置也可以查询。
{
"name": "org.apache.seatunnel.connectors.seatunnel.jdbc",
"level": "INFO",
"origin": "file",
"node": "localhost:8080"
}
覆盖单个日志器级别
POST /loggers/:name
查询参数
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| level | optional | string | OFF、FATAL、ERROR、WARN、INFO、DEBUG、TRACE 或 ALL,不区分大小写;也可放在请求体中 |
| scope | optional | string | node(默认)修改处理请求的节点,cluster 修改每个成员 |
请求体
{
"level": "DEBUG"
}
响应示例
{
"name": "org.apache.seatunnel.connectors.seatunnel.jdbc",
"level": "DEBUG",
"origin": "runtime-override",
"node": "localhost:8080",
"previousLevel": "INFO",
"status": "SUCCESS"
}
未知级别会被以 400 拒绝并返回合法级别列表,而不是被当作已应用。每次变更都会在节点日志中写一条 INFO 日志,包含 logger、旧级别与新级别、scope 和调用方地址。
示例
在单节点上将 JDBC 连接器提升到 DEBUG:
curl -X POST 'http://localhost:8080/loggers/org.apache.seatunnel.connectors.seatunnel.jdbc?level=DEBUG'
在集群所有成员上提升:
curl -X POST 'http://localhost:8080/loggers/org.apache.seatunnel.connectors.seatunnel.jdbc?level=DEBUG&scope=cluster'
撤销运行时覆盖
DELETE /loggers/:name
查询参数
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| scope | optional | string | node(默认)撤销处理请求的节点,cluster 撤销每个成员 |
logger 恢复到首次覆盖前的级别,即配置文件中的级别;若文件中未配置,则恢复为从父级继承的级别。
{
"name": "org.apache.seatunnel.connectors.seatunnel.jdbc",
"level": "INFO",
"origin": "file",
"node": "localhost:8080",
"previousLevel": "DEBUG",
"status": "SUCCESS"
}
当 logger 从未通过端点被覆盖时,status 为 NO_OVERRIDE,此时不做任何变更。
获取节点指标(Get Node Metrics)
GET /metrics
GET /openmetrics
获取指标前需要先开启 Telemetry,否则会得到空响应。Telemetry 的更多信息见 telemetry.md。
作业 Checkpoint 概览(Get Job Checkpoint Overview)
GET /jobs/checkpoints/:jobId
返回每个 pipeline 的 checkpoint 概览。
路径参数
jobId:必填作业标识。
响应示例
{
"jobId": "1234567890",
"updatedAt": 1720000000123,
"pipelines": [
{
"pipelineId": 1,
"counts": {
"triggered": 10,
"completed": 8,
"failed": 1,
"inProgress": 1,
"restored": 2
},
"latestCompleted": {
"checkpointId": 9,
"checkpointType": "CHECKPOINT_TYPE",
"status": "COMPLETED",
"triggerTimestamp": 1720000000000,
"completedTimestamp": 1720000000450,
"durationMillis": 450,
"stateSize": 128934
},
"latestFailed": {
"checkpointId": 8,
"checkpointType": "CHECKPOINT_TYPE",
"status": "FAILED",
"triggerTimestamp": 1719999995000,
"failureReason": "CHECKPOINT_EXPIRED"
},
"latestSavepoint": null,
"inProgress": [
{
"checkpointId": 10,
"checkpointType": "CHECKPOINT_TYPE",
"triggerTimestamp": 1720000005000,
"acknowledged": 2,
"total": 4
}
],
"history": [
{
"pipelineId": 1,
"checkpoint": {
"checkpointId": 9,
"checkpointType": "CHECKPOINT_TYPE",
"status": "COMPLETED",
"triggerTimestamp": 1720000000000,
"completedTimestamp": 1720000000450,
"durationMillis": 450,
"stateSize": 128934
}
}
]
}
]
}
字段说明
| Field | Description |
|---|---|
jobId |
作业 ID |
updatedAt |
最新快照时间戳(毫秒) |
pipelines |
pipeline 统计列表 |
pipelines[].pipelineId |
Pipeline ID |
pipelines[].counts.triggered/completed/failed/inProgress/restored |
Checkpoint 统计:triggered 触发的 checkpoint 总数;completed 成功总数;failed 失败总数;inProgress 进行中数量;restored 恢复(含 savepoint)尝试次数 |
pipelines[].latestCompleted/latestFailed/latestSavepoint |
最近完成/失败/savepoint checkpoint 的元数据(字段定义见下表) |
pipelines[].inProgress |
进行中的 checkpoint 详情:checkpointId、checkpointType(CHECKPOINT_TYPE、savepoint 等)、triggerTimestamp、acknowledged(已 ACK 的子任务数)、total(需要 ACK 的子任务总数) |
pipelines[].history |
环形缓冲历史(默认 32 条),按最新优先排序;每条含 pipelineId 与 checkpoint 元数据 |
Checkpoint 元数据字段:
| Field | Description |
|---|---|
checkpointId |
Checkpoint 标识 |
checkpointType |
Checkpoint 类型 |
status |
COMPLETED、FAILED 或 CANCELED |
triggerTimestamp |
触发时间(毫秒) |
completedTimestamp |
完成时间(仅成功时有) |
durationMillis |
耗时(毫秒) |
stateSize |
状态大小(字节) |
failureReason |
失败/取消原因,可选 |
作业 Checkpoint 历史(Get Job Checkpoint History)
GET /jobs/checkpoints/history/:jobId
查询参数
| Name | Description |
|---|---|
jobId |
必填作业 ID(路径) |
pipelineId |
可选 pipeline 过滤 |
limit |
可选数量限制(默认 20) |
status |
可选状态过滤:COMPLETED、FAILED、CANCELED |
响应示例
[
{
"pipelineId": 1,
"checkpoint": {
"checkpointId": 9,
"checkpointType": "CHECKPOINT_TYPE",
"status": "COMPLETED",
"triggerTimestamp": 1720000000000,
"completedTimestamp": 1720000000450,
"durationMillis": 450,
"stateSize": 128934
}
},
{
"pipelineId": 1,
"checkpoint": {
"checkpointId": 8,
"checkpointType": "CHECKPOINT_TYPE",
"status": "FAILED",
"triggerTimestamp": 1719999995000,
"failureReason": "CHECKPOINT_EXPIRED"
}
}
]
字段说明
| Field | Description |
|---|---|
pipelineId |
记录所属的 pipeline ID |
checkpoint |
上述 checkpoint 元数据 |
作业实时可观测指标(Get Job Realtime Observability Metrics)
这些 API 供 Web UI 实时指标视图使用。它们不依赖 Telemetry,也不会把历史数据写入磁盘;master 仅在内存中保留最近的时间桶。配置与指标语义见 realtime-observability.md。
列出实时指标状态
GET /metrics/realtime/jobs
响应示例
{
"jobs": [
{
"jobId": 12345,
"enabled": true,
"bucketMs": 5000,
"retentionMinutes": 3,
"latestBucketStartMs": 1700000000000
}
]
}
顶点(Source/Transform/Sink)时序
GET /metrics/realtime/jobs/{jobId}/vertices?windowMs=600000
查询参数
| Name | Required | Type | Description |
|---|---|---|---|
windowMs |
No | long | 查询窗口(毫秒),默认 3 分钟,上限 10 分钟 |
响应结构
{
"enabled": true,
"bucketMs": 5000,
"fromMs": 1700000000000,
"toMs": 1700000600000,
"vertices": [
{
"vertexId": 1,
"points": [
{
"ts": 1700000550000,
"sourceReadRatio": 0.12,
"sourceIdleRatio": 0.45,
"transformBusyRatio": 0.00,
"sinkBusyRatio": 0.00
}
]
}
]
}
Ratio 字段取值范围为 0~1,可按百分比展示;不适用的顶点类型的字段可能为 0。
队列/边时序
GET /metrics/realtime/jobs/{jobId}/edges?windowMs=600000
查询参数
| Name | Required | Type | Description |
|---|---|---|---|
windowMs |
No | long | 查询窗口(毫秒),默认 3 分钟,上限 10 分钟 |
响应结构
{
"enabled": true,
"bucketMs": 5000,
"fromMs": 1700000000000,
"toMs": 1700000600000,
"edges": [
{
"queueId": -101,
"targetVertexId": 50,
"points": [
{
"ts": 1700000550000,
"bpRatio": 0.78,
"queueFillRatio": 0.92,
"queueSize": 46,
"queueCapacity": 50
}
]
}
]
}
暂停、恢复或删除作业(Pause, Resume Or Delete A Job)
没有专用的 pause、resume、delete 端点,通过现有作业端点组合实现:
| Goal | How |
|---|---|
| 暂停运行中的作业(先停后恢复) | 调用 /stop-job 并设置 isStopWithSavePoint: true。作业停止并将当前状态的 savepoint 持久化 |
| 恢复暂停的作业 | 再次调用 /submit-job,设置 isStartWithSavePoint: true、相同的 jobId(即被停止的作业 id)与相同的作业配置。作业从该 jobId 的最新 savepoint 恢复 |
| 删除作业 | 没有删除端点。若作业仍在运行,先用 /stop-job](#stop-a-job) 停止它。作业进入终态后,其记录会在 history-job-expire-minutes(默认 1440 分钟)到期后自动移除,见 [separated-cluster-deployment.md#44-history-job-expiry-configuration |
注意:isStartWithSavePoint: true 要求请求中提供 jobId;此时不带 jobId 提交会失败,错误信息为 Please provide jobId when start with save point.。该校验逻辑在 JobInfoService.java 中有明确实现。
小结:把 REST API V2 接入你的运维体系
SeaTunnel Zeta 引擎的 RESTful API V2 覆盖了从“集群概览 → 资源快照 → 作业提交 → 运行/待调度/完成状态 → Checkpoint → 实时可观测 → 日志与日志级别 → 节点标签”的完整运维链路。把它与 Web UI(同一 Jetty 服务)配合,可以构建出脚本化、自动化的 SeaTunnel 作业管理方案:
- 监控层:用
/overview、/running-jobs、/job-info/:jobId、/jobs/checkpoints/:jobId轮询作业健康度与吞吐; - 调度层:用
/submit-job(JSON/HOCON/SQL)、/submit-job/upload、/submit-jobs实现程序化提交与批量部署; - 治理层:用
/pending-jobs定位资源瓶颈,用/stop-job(配合 savepoint)实现优雅暂停与恢复,用/update-tags管理 worker 标签调度; - 排障层:用
/loggers动态调级、/logs拉取多节点日志、/resource/workers查看 slot 与资源使用。
只要记住“Jetty 由 enable-http/enable-https 驱动、Web UI 与 REST 同源、动态端口以启动日志为准”这三个关键点,就能快速定位大多数接入问题。相关源码与配置文件的深入阅读入口已在各小节给出,可进一步追踪每个端点的精确实现。