SeaTunnel Zeta 引擎 RESTful API V2 完全指南:监控、作业提交与集群运维

原创2026-09-17 19:48:111,695 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

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 上。相关的核心文件包括:

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 同源、动态端口以启动日志为准”这三个关键点,就能快速定位大多数接入问题。相关源码与配置文件的深入阅读入口已在各小节给出,可进一步追踪每个端点的精确实现。

登录后查看全文
seatunnel