[Docs] Add Zeta slow-operation troubleshooting cookbook
- Dominant language
- Java
- Stars
- 9.7k
- Forks
- 2.4k
- Avg merge
- 3d 13h
- Merged PRs (30d)
- 203
Description
## 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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the four listed Zeta tuning and state-storage documentation files, then inspect the current Zeta/Hazelcast configuration files and runtime behavior referenced by the issue. Organize the English and Chinese content as a troubleshooting flow covering REST, master and worker pressure, checkpoint and IMap storage, restart requirements, and Kubernetes checks. Done means both language versions are consistent and the guidance is verified against the current configuration and behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, java, kubernetes
- Domain
- cloud, distributed-systems, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100