#11280·seatunnel

[Docs] Add Zeta slow-operation troubleshooting cookbook

Author: DanielLeensCreated Jul 2, 2026Updated Sep 19, 2026
Labelshelp wanteddocumentgood first issue

Background

The Zeta tuning and state recovery docs already mention Hazelcast slow operation warnings, checkpoint storage, and state recovery. However, users still need a practical troubleshooting cookbook for slow operations in real deployments.

Common questions include:

  • A job submitted through REST API stays slow on the master node for a long time.
  • Hazelcast reports SlowOperationDetector warnings.
  • IMap or checkpoint-related state is persisted to S3 and becomes slow to read or write.
  • hazelcast.operation.generic.thread.count is configured, but users are unsure whether to size it by master CPU, worker CPU, or every node.
  • Users are unsure which configuration changes require process restart instead of hot reload.

Goal

Add an operational cookbook for diagnosing Zeta/Hazelcast slow operations, with clear decision steps and safe tuning guidance.

Suggested scope

Please update English and Chinese docs. Possible locations:

  • docs/en/engines/zeta/tuning-guide.md
  • docs/zh/engines/zeta/tuning-guide.md
  • docs/en/engines/zeta/state-storage-and-recovery.md
  • docs/zh/engines/zeta/state-storage-and-recovery.md

The cookbook should explain:

  1. What Hazelcast SlowOperationDetector means in SeaTunnel Zeta.
  2. How to distinguish REST submission latency, master scheduling pressure, worker execution pressure, checkpoint storage latency, and IMap MapStore latency.
  3. How hazelcast.operation.generic.thread.count should be sized in hybrid mode and separated mode.
  4. What metrics/logs users should collect before tuning.
  5. Which config changes require restarting master/worker processes.
  6. S3 checkpoint/state storage latency checks and recommended mitigations.
  7. A short checklist for Kubernetes deployments.

Acceptance criteria

  • The docs provide a step-by-step troubleshooting flow instead of only listing tuning parameters.
  • The docs explain separated mode and hybrid mode separately.
  • English and Chinese docs are consistent.
  • The guidance is verified against the current Zeta/Hazelcast configuration files and runtime behavior.