5s - document and organize knobs

[spraza]

Just some light documentation and restructuring before I start making more changes.

100K: 20251006-211028-praza-5s-milestone1-iter30-97f19c55d684ab0de compressed=True data_size=37450858 duration=5307585 ended=100000 fail=1 fail_fast=10 max_runs=100000 pass=99999 priority=100 remaining=0 runtime=1:18:52 sanity=False started=100000 stopped=20251006-222920 submitted=20251006-211028 timeout=5400 username=praza-5s-milestone1-iter30-97f19c55d684ab0dec3b9a56a930d911075cac09. 1 failure in ParallelRestoreOldBackupCorrectnessMultiCycles (TracedTooManyLines), should not be related to this change.

Code-Reviewer Section

The general pull request guidelines can be found here.

Please check each of the following things and check all boxes before accepting a PR.

• The PR has a description, explaining both the problem and the solution.
• The description mentions which forms of testing were done and the testing seems reasonable.
• Every function/class/actor that was touched is reasonably well documented.

For Release-Branches

If this PR is made against a release-branch, please also check the following:

• This change/bugfix is a cherry-pick from the next younger branch (younger release-branch or main if this is the youngest branch)
• There is a good reason why this PR needs to go into a release branch and this reason is documented (either in the description above or in a linked GitHub issue)

[foundationdb-ci]

Result of foundationdb-pr-clang-ide on Linux RHEL 9

• Commit ID: 1a96a75
• Duration 0:39:22
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang-ide on Linux RHEL 9

• Commit ID: 97f19c5
• Duration 0:40:09
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang-arm on Linux CentOS 7

• Commit ID: 1a96a75
• Duration 0:48:18
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang-arm on Linux CentOS 7

• Commit ID: 97f19c5
• Duration 0:48:21
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-cluster-tests on Linux RHEL 9

• Commit ID: 1a96a75
• Duration 0:55:02
• Result: ❌ FAILED
• Error: Error while executing command: docker build --label "org.foundationdb.version=${FDB_VERSION}" --label "org.foundationdb.build_date=${BUILD_DATE}" --label "org.foundationdb.commit=${COMMIT_SHA}" --progress plain --build-arg FDB_VERSION="${FDB_VERSION}" --build-arg FDB_LIBRARY_VERSIONS="${FDB_VERSION}" --build-arg FDB_WEBSITE="${FDB_WEBSITE}" --tag foundationdb/foundationdb-kubernetes-sidecar:${FDB_VERSION}-${COMMIT_SHA}-1 --file Dockerfile --target foundationdb-kubernetes-sidecar .. Reason: exit status 1
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)
• Cluster Test Logs zip file of the test logs (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-cluster-tests on Linux RHEL 9

• Commit ID: 97f19c5
• Duration 1:16:17
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)
• Cluster Test Logs zip file of the test logs (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr on Linux RHEL 9

• Commit ID: 97f19c5
• Duration 1:30:51
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang on Linux RHEL 9

• Commit ID: 97f19c5
• Duration 1:31:32
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang on Linux RHEL 9

• Commit ID: 1a96a75
• Duration 1:34:43
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr on Linux RHEL 9

• Commit ID: 1a96a75
• Duration 1:34:43
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[dlambrig]

applies on the commit path - governs how far back in history a commit request is still accepted. put another way- proxies/resolvers refuse to commit a transaction whose read version is more than this many versions behind the current commit version, returning transaction_too_old.

[spraza]

updated

[dlambrig]

comments can describe these knobs - this one governs how long versioned data stay readable on storage servers. In other words when a client’s read version falls more than this many versions behind the storage servers’ latest durable version, the storage server replies with past_version. Practically, it’s the MVCC retention budget.

[spraza]

Yeah, I was thinking to add more details but given the variety of usage across roles, I am still figuring out "why" this knob is needed in let's say RK, LR, etc. For SS though, the MVCC reasoning is clear. Your comment makes sense. I'll update the PR.

[dlambrig]

I believe the LR can never hold more than MAX_READ_TRANSACTION_LIFE_VERSIONS worth of versions in flight (remote storage servers can roll back only that far), but @sbodagala may be more familiar.

[spraza]

when a client’s read version falls more than this many versions behind the storage servers’ latest durable version

I believe instead of durable version, this is the latest committed version (in memory). The actual logic involves min kcv as well:

foundationdb/fdbserver/storageserver.actor.cpp

Lines 12537 to 12538 in 442e150

	Version proposedOldestVersion =
	std::max(data->version.get(), cursor->getMinKnownCommittedVersion()) - maxVersionsInMemory;

.

the storage server replies with past_version

The exact error code seems to be transaction_too_old

[spraza]

@dlambrig updated the comment, made some changes based on my understanding above

[foundationdb-ci]

Result of foundationdb-pr-clang-ide on Linux RHEL 9

• Commit ID: 4fec7bf
• Duration 0:32:30
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang-arm on Linux CentOS 7

• Commit ID: 4fec7bf
• Duration 0:47:38
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-cluster-tests on Linux RHEL 9

• Commit ID: 4fec7bf
• Duration 1:12:55
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)
• Cluster Test Logs zip file of the test logs (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr-clang on Linux RHEL 9

• Commit ID: 4fec7bf
• Duration 1:17:57
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)

[foundationdb-ci]

Result of foundationdb-pr on Linux RHEL 9

• Commit ID: 4fec7bf
• Duration 1:21:01
• Result: ✅ SUCCEEDED
• Error: N/A
• Build Log terminal output (available for 30 days)
• Build Workspace zip file of the working directory (available for 30 days)