Clarify uncertainty error keys and document randomized anchor key tuning#22814
Open
rmloveland wants to merge 2 commits intomainfrom
Open
Clarify uncertainty error keys and document randomized anchor key tuning#22814rmloveland wants to merge 2 commits intomainfrom
rmloveland wants to merge 2 commits intomainfrom
Conversation
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
rmloveland
force-pushed
the
20260223-DOC-15172-DOC-14735-randomized-anchor-keys
branch
2 times, most recently
from
c2829cd to
1ada635
Compare
rmloveland
force-pushed
the
20260223-DOC-15172-DOC-14735-randomized-anchor-keys
branch
from
1ada635 to
8988c8a
Compare
Fixes: - DOC-14735 - DOC-15172 Summary of changes: - v25.4 and below, and v26.1 and later: - Update ReadWithinUncertaintyIntervalError docs to: - Extend the example to include a larger `meta={key=/Table/...}` fragment - Add randomized anchor key tuning guidance to the shared `performance/reduce-contention.md` include: - Describe when to consider `transaction.randomized_anchor_key.enabled` for workloads with large concurrent UPDATE/INSERT batches that create transaction record (anchor) hotspots - Emphasize that this setting randomizes anchor placement (not user data) to spread txn records across ranges - In v26.1, tie this guidance to the improved observability: contention events and logs already report the actual contention key, so anchor randomization is a secondary knob once true conflict locations are understood - v25.4 and below only: - Update ReadWithinUncertaintyIntervalError docs to: - Add an "Interpreting log messages" callout explaining that the logged key is the transaction record (anchor) key, not necessarily the actual conflict key - Note that SERIALIZATION_CONFLICT contention events recorded when `sql.contention.record_serialization_conflicts.enabled` is true also use this anchor key - v26.1 and later only: - Update ReadWithinUncertaintyIntervalError docs to: - Add an "Interpreting log messages" callout clarifying that in 26.1+ the logged key represents the actual contention key, and that earlier versions reported the anchor key - Document that contention events now use this contention key when the `sql.contention.record_serialization_conflicts.enabled` setting is enabled - Update 'Troubleshoot lock contention' page to include a new section on using randomized anchor keys
rmloveland
force-pushed
the
20260223-DOC-15172-DOC-14735-randomized-anchor-keys
branch
from
8988c8a to
db794d9
Compare
rmloveland
commented
Feb 24, 2026
rmloveland
commented
Feb 24, 2026
rmloveland
commented
Feb 24, 2026
rmloveland
commented
Feb 24, 2026
Contributor
Author
|
@arulajmani pinged you for review since this came out of your KV on-call a while ago (details in https://cockroachlabs.atlassian.net/browse/DOC-15172) @angles-n-daemons pinging you since we discussed your changes to the txn record key in v26.1 and later in Slack (docs issue is https://cockroachlabs.atlassian.net/browse/DOC-14735) cc @michae2, i already asked @angles-n-daemons to review the txn record key stuff, but FYI this closes out DOC-14735 which was prompted by you answering a q in slack a long time ago :-) |
angles-n-daemons
approved these changes
Feb 24, 2026
angles-n-daemons
left a comment
angles-n-daemons
left a comment
There was a problem hiding this comment.
thanks for the changes, looks good on my side :)
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.
Clarify uncertainty error keys and document randomized anchor key tuning
Fixes:
Summary of changes:
v25.4 and below, and v26.1 and later:
meta={key=/Table/...}fragmentperformance/reduce-contention.mdinclude:
transaction.randomized_anchor_key.enabledfor workloads withlarge concurrent UPDATE/INSERT batches that create transaction record (anchor) hotspots
records across ranges
and logs already report the actual contention key, so anchor randomization is a
secondary knob once true conflict locations are understood
v25.4 and below only:
transaction record (anchor) key, not necessarily the actual conflict key
sql.contention.record_serialization_conflicts.enabledis true also use this anchor keyv26.1 and later only:
represents the actual contention key, and that earlier versions reported the anchor key
sql.contention.record_serialization_conflicts.enabledsetting is enabledanchor keys