CAS: doc for GC round - #2312
Merged
Merged
Conversation
Signed-off-by: Konstantin Morozov <just.morozov.k@gmail.com>
Signed-off-by: Konstantin Morozov <just.morozov.k@gmail.com>
Signed-off-by: Konstantin Morozov <just.morozov.k@gmail.com>
Signed-off-by: Konstantin Morozov <just.morozov.k@gmail.com>
k-morozov
marked this pull request as ready for review
September 8, 2026 12:07
Signed-off-by: Mikhail Filimonov <mfilimonov@altinity.com>
Every claim on the page was checked against the GC implementation and brought in line with the current `antalya-26.6` code. Commands and tools: the `clickhouse-disks` applets are `cas-gc-rebuild`, `cas-gc-dryrun` and `cas-fsck`; `SYSTEM CAS GC RUN` takes an optional disk while `STOP`, `START`, `REBUILD [FORCE]` and `FSCK` require one; only the `CORRUPTED_DATA` errors that name `REBUILD` point at it. Deletion semantics: the condemnation diagram stores `condemn_round = n`, not `n+1`; `delete_pending` is not terminal (recovered in-degree spares the entry); `GC` is the only blob deleter but writers and pool-member decommission also delete manifests, so phase 11 is the single blob-body delete site; phase 11 observes each entry with a `HEAD` before a conditional `DELETE`; phases 15 and 17 delete write-once keys in batch chunks of `cas_gc_bulk_delete_chunk_keys` with authority re-validated per chunk; phase 14 is one-shot and may leave a partially drained generation to `cas-fsck`; phase 17 keys snapshot deletion to the checkpoint-named snapshot; the 404 rule is scoped to manifest-edge folding; `cas_gc_shards` is fixed in `_pool_meta` at pool creation; reducers run sequentially today. Errors and outcomes: a new "post-commit failures" subsection explains that phases 14, 15, 17 and 18 let backend exceptions propagate after the commit; a new "round outcomes" subsection documents `Aborted` (transient codes, leadership kept), `Stopped`, `Error` and the `error_code` column; `logs_accounted != logs_applied` and `transactions_unapplied` are documented once, between phases 9 and 10. Tables: phases 2-4 and 16 run on every leader round (16 also on `DEFER`); the phase-3 fence-out is a token-guarded `PUT`; phase 7's second seal read is the known redundant one (`redundant_reads`); the adopted seal is read six times; manifest `GET`s are per owner edge; the deferred-round cost includes phases 2, 4 and the suppressed janitor page; every count is a conflict-free lower bound. The anomaly table is split into durable holds (six wire names, `body_undecodable` was missing), per-round suppression signals and fatal checks. Settings: the per-round budgets are ordinary `cas_gc_round_*` and `cas_manifest_sweep_*` disk settings, listed with defaults and linked to the advanced pacing section of the configuration page; the fold thresholds are marked internal. The fold's read-ahead pool (`cas_gc_read_concurrency`, `CASGCReadAheadHit`/`Miss`/`Wasted`), the mount-floor memo of the orphan sweep and the mount-lease settings behind the heartbeat-floor threshold are described. Observability: `system.cas_log` has no per-anomaly rows (`GcAnomaly` is never emitted; holds are `GcFoldClamp` events); the `round` column is `0` on a `NotALeader` finish; `cas-fsck` reports `unreachable` as a rollup of `pending_gc`, `awaiting_gc`, `unaccounted` and manifest debris; phase 18's four `retained_*` metrics are named. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Mikhail Filimonov <mfilimonov@altinity.com>
…here The tools are registered as `cas-fsck`, `cas-inspect`, `cas-gc-dryrun` and `cas-gc-rebuild` in `programs/disks/DisksApp.cpp`, but seven pages under `docs/en/antalya/cas` still used the older `ca-*` spelling next to the `cas-*` one, so a reader could not tell which form is current. Rename the stale mentions; `ca-pool` (an example bucket prefix) and `utils/ca-soak` are real names and stay. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> (cherry picked from commit af2aa73066a0c9b66642b89fb231b65be428fc36) Signed-off-by: Mikhail Filimonov <mfilimonov@altinity.com>
Retries: the lease `CAS`, a lost steal and the mount fence-out are re-observed and re-decided by the request engine within the standard write policy, not "one retry" or "up to four". Phase 18 issues a `HEAD` per nomination before a conditional `DELETE`, and its leftovers return only when the sweep cursor wraps. `redeleted` and `cas_gc_round_redelete_budget` count entries processed, not deletes sent. `GcRoundWorkBudget` is described per family: graduation and redelete overflow is carried, outcome-log overflow is not logged, the hand-off is one-shot, phase 18 is bounded through phase 9. Namespace cleanup under suppression still classifies one page. Hold wire names are seal values; `GcFoldClamp` carries prose. The three checkpoint frontier states are log-only, not `phase_metrics`. `0` is unbounded for `cas_gc_round_*` only; the sweep list budget disables, the pools and chunk size reject it. Prefix budgets count listed objects. `CASGCReadAheadWasted` lands in the round-level counters. `error_code` is set on `Aborted`, `Stopped` and `Error` only. A phase-13 backend or deadline failure keeps its own code. A retry-exhausted batch also leaves phase-15 entries to the sweep. `cas-fsck`'s `stale_edge` and `corrupted_runs` are hard findings, not backlog. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Mikhail Filimonov <mfilimonov@altinity.com>
Signed-off-by: Mikhail Filimonov <mfilimonov@altinity.com>
filimonov
force-pushed
the
docs/gc-round
branch
from
September 17, 2026 19:51
38ad6b5 to
cdf1421
Compare
Collaborator
|
No need for QA verification, this is a doc-change only |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changelog category (leave one):
Changelog entry (a user-readable short description of the changes that goes to CHANGELOG.md):
...
Documentation entry for user-facing changes
...
CI/CD Options
Exclude tests:
Regression jobs to run: