You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by "DanielLeens (via GitHub)" <gi...@apache.org> on 2026/08/08 16:04:18 UTC

[PR] [Docs][Zeta] Clarify job.retry.times counts cumulatively, never resets [seatunnel]

DanielLeens opened a new pull request, #11708:
URL: https://github.com/apache/seatunnel/pull/11708

   ### Purpose of this pull request
   
   A user asked (via a support-bot Q&A export reviewed for documentation gaps): if `job.retry.times`
   is set to e.g. 5, a pipeline fails and recovers successfully 3 times, then runs fine for a while
   before failing again -- does the next retry attempt count as retry #1 again, or retry #4?
   
   Verified against `seatunnel-engine-server`'s `SubPlan.java`:
   - `pipelineRestoreNum` is a plain `AtomicInteger`, incremented only via `getAndIncrement()` inside
     `prepareRestorePipeline()`.
   - It is never reset anywhere else in the class -- not after a successful restore, not after any
     amount of subsequent healthy running time.
   - The restore-eligibility check (`needRestore()`) is `getPipelineRestoreNum() < pipelineMaxRestoreNum`,
     a plain cumulative comparison for the whole lifetime of that pipeline's `SubPlan` instance (i.e.
     the whole job run, from submission to final completion/cancellation).
   
   So the answer is: it's cumulative and never resets. With the default `job.retry.times = 3`, once a
   pipeline has used up all 3 retries -- even if they were spread across days of otherwise-healthy
   running -- the next failure is terminal. The only way to get a fresh retry budget is to resubmit the
   job as a new run.
   
   The existing doc for `job.retry.times` only said "Used to control the default retry times when a job
   fails. The default value is 3" -- it didn't address this at all, which is presumably why the
   cumulative/non-reset behavior keeps surprising users. Added an explicit explanation with a worked
   example to `docs/en/introduction/configuration/JobEnvConfig.md` and its `docs/zh` counterpart.
   
   ### Does this PR introduce _any_ user-facing change?
   
   No functional change. Documentation-only addition.
   
   ### How was this patch tested?
   
   Documentation-only change, so `./mvnw spotless:apply` is a no-op (spotless in this repo only formats
   `<java>` and `<pom>`, not markdown). The behavioral claim was verified directly against current `dev`
   HEAD source, not inferred from existing docs:
   - `seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/dag/physical/SubPlan.java`
     -- traced every reference to `pipelineRestoreNum` (declaration, constructor init, the single
     `getAndIncrement()` call site in `prepareRestorePipeline()`, the `needRestore()` comparison against
     `pipelineMaxRestoreNum`, and the getter) to confirm there is no reset path.
   - `seatunnel-api/src/main/java/org/apache/seatunnel/api/options/EnvCommonOptions.java` -- confirmed
     `JOB_RETRY_TIMES` default value (3) matches the existing doc text.
   
   ### Check list
   
   * [x] No new JAR binary package is added.
   * [x] English and Chinese documentation both updated.
   * [x] No incompatible configuration or API change is introduced (docs-only).
   * [x] N/A -- documentation-only change, no test coverage applicable.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Docs][Zeta] Clarify job.retry.times counts cumulatively, never resets [seatunnel]

Posted by "DanielLeens (via GitHub)" <gi...@apache.org>.
DanielLeens commented on PR #11708:
URL: https://github.com/apache/seatunnel/pull/11708#issuecomment-5340767722

   # Re-verification Update (2026-08-19) — no new commit or reply since my 2026-08-16 review
   
   I re-ran this as a full fresh pass rather than skipping it for lack of new activity, since this is my own PR and I want to make sure the conclusion still reflects the current `dev` state rather than going stale.
   
   **Facts re-checked at this head:**
   - PR head is still `e3f0c2176ae5bf1b855cdda65db5ef9d572d408a` — unchanged since 2026-08-16, no new commits, no new comments from anyone.
   - `gh api .../pulls/11708/files` still reports `changed_files: 0`, `additions: 0`, `deletions: 0`.
   - `git diff origin/dev HEAD -- docs/en/introduction/configuration/JobEnvConfig.md docs/zh/introduction/configuration/JobEnvConfig.md` against the *current* `dev` tip (`2586f37e`, as of 2026-08-19) is still completely empty — the two files remain byte-identical to `dev`.
   - `dev`'s `JobEnvConfig.md:48` still carries the accurate clarification from #11748: cumulative counter, no reset on intermediate successful recovery, and explicitly calls out the active-master-failover exception.
   - I re-traced the underlying source again against current `dev` to make sure nothing drifted since 08-16: `SubPlan.java:102/129` (`pipelineRestoreNum` is still a plain in-memory `AtomicInteger`, initialized only in the constructor), `SubPlan.java:492` (still the sole `getAndIncrement()`), `SubPlan.java:425-435` (`reset()`, invoked on every restore attempt, still does not touch the field), and `CoordinatorService.java:1010/1056` (`restoreJobFromMasterActiveSwitch` → `jobMaster.init(..., true)` still rebuilds the `SubPlan` graph, still the one non-resubmission reset path). All of it is unchanged and confirms the same conclusion as before: the underlying behavioral claim this PR set out to document (`job.retry.times` is a cumulative, per-pipeline counter that survives successful recoveries and is only reset by resubmission or a master active-switch) is **true**, and it is **already fully and more accurately documented on `dev` via #11748**.
   - `compare/dev...HEAD`: `status=diverged`, `ahead_by=2`, `behind_by=28`. `mergeable=true`, `mergeable_state=blocked` (this reflects the `REVIEW_REQUIRED` gate, not a merge conflict — there is nothing left in the diff to conflict with). CI is green: `Build` / `Notify test workflow` / `labeler` all pass.
   
   Nothing here changes my 2026-08-16 conclusion, so I'm not asking for anything new — just confirming it's still accurate against the latest source rather than leaving a stale-looking review sitting on the PR.
   
   # Merge Recommendation
   
   ### Conclusion: Not recommended for merge — close as superseded by #11748
   
   The technical question this PR raised was worth asking, and the answer is correct and verified end-to-end against the current engine source: `job.retry.times` really is a per-pipeline, cumulative, monotonic counter (`SubPlan.pipelineRestoreNum`) that is never reset by an intermediate successful recovery, and the one real reset trigger beyond resubmission is a Zeta active-master failover rebuilding the plan (`CoordinatorService.restoreJobFromMasterActiveSwitch` → `JobMaster.init(..., true)`). That's exactly what's now documented on `dev` at `JobEnvConfig.md:48` via #11748 — with wording that's strictly more accurate than this PR's own original sentence, which incorrectly claimed resubmission was "the only way" to reset the counter.
   
   This branch's own conflict-resolution merge already resolved everything in favor of `dev`, which was the right call on the merits, but it also means the PR is now an empty diff (0 files changed) with nothing left to merge. Landing it as-is would only add a no-op merge commit to `dev` history. There's no code-side blocker and no compatibility/behavioral risk — this is purely a housekeeping item.
   
   1. **Blockers — must be fixed**
      - None from a content/correctness standpoint. The only reason this PR can't be merged is that it has no remaining diff.
   2. **Recommended fixes — non-blocking**
      - Close this PR as superseded by #11748 rather than pushing a commit to re-add the (less accurate) original paragraph. If any residual value is wanted, the only real follow-up is a dedicated unit test pinning "no reset on intermediate successful recovery" plus the master-failover exception in `seatunnel-engine-server` — that belongs in a separate PR against `seatunnel-engine`, not here.
   
   Since the goal this PR set out to achieve is already live on `dev`, closing it as superseded is the appropriate next step here rather than keeping an empty-diff PR open.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Docs][Zeta] Clarify job.retry.times counts cumulatively, never resets [seatunnel]

Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo closed pull request #11708: [Docs][Zeta] Clarify job.retry.times counts cumulatively, never resets
URL: https://github.com/apache/seatunnel/pull/11708


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Docs][Zeta] Clarify job.retry.times counts cumulatively, never resets [seatunnel]

Posted by "DanielLeens (via GitHub)" <gi...@apache.org>.
DanielLeens commented on PR #11708:
URL: https://github.com/apache/seatunnel/pull/11708#issuecomment-5379306717

   # What Problem Does This PR Solve?
   
   - User pain point: the original `job.retry.times` doc only said "the default value is 3," leaving it ambiguous whether the retry counter is per-failure-episode or cumulative for the pipeline's whole life, and whether a long healthy run "buys back" retry budget.
   - Fix approach: this PR's own commit (`6f49d488c1ac`) added one explanatory paragraph to `docs/en` and `docs/zh` stating the counter is per-pipeline, cumulative, and never reset by a successful recovery.
   - One-sentence summary: the underlying behavioral claim is correct and verified against the current engine source, but the branch itself is now an empty diff — the same content, with a more accurate caveat this PR's own wording lacked, already landed on `dev` through PR #11748, and nothing remains here to merge.
   
   # 1. Code Change Review
   
   ## 1.1 Core Logic Analysis
   
   **Status of this round.** Head is still `e3f0c2176ae5bf1b855cdda65db5ef9d572d408a` (unchanged since 2026-08-14). No new commit and no new comment/review from anyone since my last check on 2026-08-21. I re-verified, rather than assumed, that this remains true:
   
   - `gh api repos/apache/seatunnel/pulls/11708` at this moment reports `changed_files: 0`, `additions: 0`, `deletions: 0` — same as every check since 2026-08-16.
   - `git diff` between the PR head and current `dev` tip for `docs/en/introduction/configuration/JobEnvConfig.md` and `docs/zh/introduction/configuration/JobEnvConfig.md` is empty — both files remain byte-identical to `dev`, which has moved further since my last check (now `behind_by=48` vs. `28` on 2026-08-19) with no further edits to this section.
   - `dev`'s current text at `docs/en/introduction/configuration/JobEnvConfig.md` (immediately after the `job.retry.times` default-value sentence) still reads: "This counter accumulates for the life of the pipeline; an intermediate successful recovery does not reset it. For example, with `job.retry.times = 5` ... The one exception is an active-master failover in a Zeta cluster, which rebuilds the pipeline execution plan (and its retry counter) from scratch." This is the #11748 wording, and it is strictly more accurate than this PR's own original sentence ("resubmitting the job ... is the only way to reset the counter"), which omitted the master-failover reset path — the exact gap I originally flagged as Issue 1 on 2026-08-10.
   - `mergeable: true`, `mergeable_state: blocked` — the `REVIEW_REQUIRED` gate, not a conflict, consistent with there being nothing left in the diff to conflict with.
   
   I am not re-deriving the underlying `SubPlan.pipelineRestoreNum` / `CoordinatorService.restoreJobFromMasterActiveSwitch` call chain a third time in full — I traced it end to end (declaration, sole increment site, `reset()` deliberately not touching it, the monotonic gate, and the two `JobMaster.init()` call sites) in my 2026-08-16 review, which is still visible on this PR and whose file:line citations I re-spot-checked this round against current `dev` source without finding drift.
   
   ## 1.2 Compatibility Impact
   
   **Fully compatible / not applicable** (unchanged) — the diff is empty, so trivially no API, config, checkpoint, or serialization surface is touched.
   
   ## 1.3 Performance / Side-Effect Analysis
   
   None — no code or runtime path is touched.
   
   ## 1.4 Error Handling and Logging
   
   Not applicable — no code changed.
   
   # 2. Code Quality Assessment
   
   ## 2.1 Coding Standards
   
   Not applicable — docs-only, and the diff is currently empty.
   
   ## 2.2 Test Coverage and Test Stability
   
   No tests changed, correctly so for a docs PR. As noted in my 2026-08-16 review, the underlying documented behavior ("no reset on an intermediate successful recovery," plus the master-failover exception) still has no direct test coverage of its own — `CheckpointErrorRestoreEndTest.java` and `JobClientJobProxyIT.java` only exercise continuous-failure paths. This is a pre-existing gap in `seatunnel-engine`, not something this PR should be asked to fix (Issue 2, Low, informational).
   
   ## 2.3 Documentation Updates
   
   The content this PR set out to add is fully present on `dev` (via #11748), in both `docs/en` and `docs/zh`, in a form that is more accurate than this PR's own original wording. There is nothing left for this PR itself to contribute.
   
   # 3. Architectural Soundness
   
   ## 3.1 Elegance of the Solution
   
   The original intent was well-judged — document real, previously-undocumented, verified behavior in the exact place a user configuring `job.retry.times` will read it. The PR's current state, however, is not a solution at all: its conflict-resolution merge on 2026-08-14 correctly resolved everything in favor of `dev`, leaving an empty branch.
   
   ## 3.2 Maintainability / 3.3 Extensibility
   
   Not applicable to an empty diff.
   
   ## 3.4 Historical-Version Compatibility
   
   Not applicable — documentation only, no behavior, upgrade, or serialization surface touched, and the documented behavior itself is long-standing and unchanged.
   
   # 4. Issue Summary
   
   | # | Issue | Location | Severity | Status |
   |---|---|---|---|---|
   | 1 | PR is an empty diff (0 files / 0 additions / 0 deletions); the content it set out to add is already on `dev` via #11748, in a more accurate form (includes the active-master-failover reset caveat this PR's own wording omitted) | whole PR; intended targets `docs/en/introduction/configuration/JobEnvConfig.md:48`, `docs/zh/introduction/configuration/JobEnvConfig.md:48` | Medium | Still true, re-verified this round (`dev` has moved 20 commits further since my last check with no further edits to this section) |
   | 2 | The documented "no reset on an intermediate successful recovery" behavior, and the master-failover exception, have no direct test coverage in `seatunnel-engine-server` | `CheckpointErrorRestoreEndTest.java:38-64`, `JobClientJobProxyIT.java:52-64` | Low | Pre-existing gap, out of this PR's scope |
   
   # 5. Merge Recommendation
   
   ### Conclusion: Not recommended for merge — close as superseded by #11748
   
   1. **Blockers**
      - Issue 1 (Medium): there is nothing to merge. The correct disposition is to close this PR as superseded, not to merge an empty commit and not to push a commit re-adding the original (less accurate) paragraph.
   
   2. **Recommended (non-blocking)**
      - Issue 2 (Low): a follow-up unit test in `seatunnel-engine-server` pinning "no reset after a successful intermediate recovery" plus the master-failover exception would be valuable, but belongs in a separate PR against `seatunnel-engine`, not here.
   
   **Overall assessment.** No reviewer other than myself has commented on this PR, so there is no other position to reconcile. The technical question this PR raised was worth asking and the answer is correct and re-verified again this round against current `dev` source: `job.retry.times` is a per-pipeline, cumulative, monotonic counter that survives successful recoveries, with the one real reset trigger beyond resubmission being a Zeta active-master failover. That outcome is fully and more accurately achieved on `dev` today through #11748. CI is green at this head. Since this is purely a bookkeeping item with zero correctness or compatibility risk, I'd suggest the author (myself) close this PR as superseded rather than leaving an empty-diff branch open for future reviewer attention.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org