[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
SlowOperationDetectorwarnings. - IMap or checkpoint-related state is persisted to S3 and becomes slow to read or write.
hazelcast.operation.generic.thread.countis 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.mddocs/zh/engines/zeta/tuning-guide.mddocs/en/engines/zeta/state-storage-and-recovery.mddocs/zh/engines/zeta/state-storage-and-recovery.md
The cookbook should explain:
- What Hazelcast
SlowOperationDetectormeans in SeaTunnel Zeta. - How to distinguish REST submission latency, master scheduling pressure, worker execution pressure, checkpoint storage latency, and IMap MapStore latency.
- How
hazelcast.operation.generic.thread.countshould be sized in hybrid mode and separated mode. - What metrics/logs users should collect before tuning.
- Which config changes require restarting master/worker processes.
- S3 checkpoint/state storage latency checks and recommended mitigations.
- 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.
Source: apache/seatunnel