Doc 13694 #4076

TimLFletcher · 2026-01-22T13:41:52Z

https://jira.issues.couchbase.com/browse/DOC-13694

Part of a CBSE so of some priority.

Split lock is a feature that locks memory when an atomic instruction is split along two cache lines. When working as intended, it can dramatically slow CB processes for no major benefit. Thus, some information on how to mitigate.

I've added details to the deployment guidelines as well as troubleshooting doc. Also did a minor cleanup on the troubleshooting doc although I admit this is basically a drop in the ocean. Links tested and working.

TimLFletcher · 2026-01-22T13:47:47Z

I'll also note that I did consider making a partial for this. But with 2 only pages and with info that is highly unlikely to change, I didn't think a partial would reduce the complexity of maintenance.

sarahlwelton

Some fixes please :)

sarahlwelton · 2026-01-22T14:26:37Z

modules/ROOT/nav.adoc

 ** xref:install:thp-disable.adoc[Disable THP]
 ** xref:install:install-swap-space.adoc[Configure Kernel Swappiness]
 ** xref:install:install-security-bp.adoc[Security Considerations]
+ ** xref:install:install-splitlock-mitigation.adoc[Split lock mitigation]


Suggested change

** xref:install:install-splitlock-mitigation.adoc[Split lock mitigation]

** xref:install:install-splitlock-mitigation.adoc[]

Title case for topic titles. Also no need to add this, it will populate from the title in the .adoc file. But change to title case if you do want to keep it, please.

sarahlwelton · 2026-01-22T14:27:24Z

modules/install/pages/install-production-deployment.adoc

 xref:deployment-considerations-lt-3nodes.adoc[About Deploying Clusters With Less Than Three Nodes]
+
+| *Split lock*
+| On some CPUs, the kernel's split lock mitigation can cause a severe performance drop when a process triggers a misaligned atomic memory access ("split lock").


Why is the term in the definition that we're providing for it? Can we find a better way to phrase this?

Also please try to avoid using quotation marks.

sarahlwelton · 2026-01-22T14:28:03Z

modules/install/pages/install-splitlock-mitigation.adoc

@@ -0,0 +1,42 @@
+= Split Lock Mitigation
+
+:description: Disable Linux split lock mitigation on affected systems


Suggested change

:description: Disable Linux split lock mitigation on affected systems

:description: Learn how to disable Linux split lock mitigation on affected systems.

Do you want to add a keywords attribute to your front matter, too?

sarahlwelton · 2026-01-22T14:28:33Z

modules/install/pages/install-splitlock-mitigation.adoc

+[abstract]
+{description}
+
+On some Linux kernels that support split lock detection, the kernel's split lock mitigation can cause a severe performance drop when a process triggers a misaligned atomic memory access ("split lock").


Same comment as before, just having the word in use before we define it seems... Off.

sarahlwelton · 2026-01-22T14:29:36Z

modules/install/pages/install-splitlock-mitigation.adoc

+Disabling split lock mitigation changes kernel behavior intended to reduce the impact of split locks.
+Apply this setting only on systems where you have confirmed it's contributing to performance degradation.
+
+For background, see: https://lwn.net/Articles/790464/


Please properly introduce and format the link. Give users some hint about where you're sending them.

See: https://docs.couchbase.com/styleguide/links.html

I think I will push back on the dev for including this. It's not an official source.... don't like it.

sarahlwelton · 2026-01-22T14:35:41Z

modules/manage/pages/troubleshoot/common-errors.adoc

+=== Resolution
+
+Disable split lock mitigation on the affected Couchbase Server host.
+
+. Permanent (boot-time) fix
+
+Add `split_lock_detect=off` to the kernel command line and reboot the host.
+
+[source,bash]
+----
+# Example kernel cmdline parameter
+split_lock_detect=off
+----
+
+. Immediate (runtime) mitigation (kernel-dependent)
+
+If present on your kernel, you can disable mitigation via `/proc`:
+
+[source,bash]
+----
+echo 0 > /proc/sys/kernel/split_lock_mitigate
+----


Do we want to repeat this or just link to the page with details? No need for a partial, just a link.

Fair. I will leave some details on the symptoms and link to the fix.

sarahlwelton · 2026-01-22T14:36:40Z

modules/manage/pages/troubleshoot/common-errors.adoc

 Typically, to enable certain features like client-server SSL, or secure XDCR; all the nodes of the cluster to be at a required compatibility level or higher that supports the feature.

-Difficulties communicating with the cluster. Displaying cached information.::
+== Difficulties communicating with the cluster. Displaying cached information.


Suggested change

== Difficulties communicating with the cluster. Displaying cached information.

== Difficulties Communicating With The Cluster. Displaying Cached Information.

sarahlwelton · 2026-01-22T14:36:59Z

modules/manage/pages/troubleshoot/common-errors.adoc

 This error often occurs due to a networking issue, particularly around DHCP and DNS resolution.

-Cluster version compatibility mismatch::
+== Cluster version compatibility mismatch


Suggested change

== Cluster version compatibility mismatch

== Cluster Version Compatibility Mismatch

sarahlwelton · 2026-01-22T14:37:20Z

modules/manage/pages/troubleshoot/common-errors.adoc

 ----

-IP address seems to have changed::
+== IP address seems to have changed


Suggested change

== IP address seems to have changed

== IP Address Seems To Have Changed

sarahlwelton · 2026-01-22T14:37:48Z

modules/manage/pages/troubleshoot/common-errors.adoc

 {description}

-File descriptor and core file size limits::
+== File descriptor and core file size limits


Suggested change

== File descriptor and core file size limits

== File Descriptor and Core File Size Limits

TimLFletcher · 2026-01-26T12:16:40Z

Rewrote as a procedure

sarahlwelton

Just one nit.

sarahlwelton · 2026-01-26T16:21:32Z

modules/manage/pages/troubleshoot/common-errors.adoc

+If the CPU supports split lock detection, a misaligned atomic memory access can trigger Linux split lock mitigation.
+The mitigation can artificially slow execution, causing a pronounced performance drop for the affected workload.
+
+For mitigating information, see the article on xref:install:install-splitlock-mitigation.adoc[]


Suggested change

For mitigating information, see the article on xref:install:install-splitlock-mitigation.adoc[]

For more information about how to resolve issues with split lock mitigation, see xref:install:install-splitlock-mitigation.adoc[].

Thanks. Fixed.

sarahlwelton

🚢

TimLFletcher added 3 commits January 22, 2026 13:05

splitlock mitigation changes

16f7e96

Made the changes linux focused

ece64aa

fixed a few formatting issues

a74444c

sarahlwelton requested changes Jan 22, 2026

View reviewed changes

TimLFletcher added 6 commits January 22, 2026 14:56

Sarah's suggestions

c44c880

rewrote splitlock definitions

df4937a

more errors cleaned up

1ea5675

dropped a redundant header

e5886ff

rewrote as procedure

0696370

retitled and cleaned up nav

3d6afa1

TimLFletcher requested a review from sarahlwelton January 26, 2026 12:16

sarahlwelton requested changes Jan 26, 2026

View reviewed changes

improved link direction

dd26397

TimLFletcher requested a review from sarahlwelton January 26, 2026 16:25

sarahlwelton approved these changes Jan 26, 2026

View reviewed changes

TimLFletcher merged commit 8eb4512 into release/8.0 Jan 26, 2026

TimLFletcher deleted the DOC-13694 branch January 26, 2026 17:12

	** xref:install:install-splitlock-mitigation.adoc[Split lock mitigation]
	** xref:install:install-splitlock-mitigation.adoc[]

		@@ -0,0 +1,42 @@
		= Split Lock Mitigation

		:description: Disable Linux split lock mitigation on affected systems

	:description: Disable Linux split lock mitigation on affected systems
	:description: Learn how to disable Linux split lock mitigation on affected systems.

	== Difficulties communicating with the cluster. Displaying cached information.
	== Difficulties Communicating With The Cluster. Displaying Cached Information.

	== Cluster version compatibility mismatch
	== Cluster Version Compatibility Mismatch

	== IP address seems to have changed
	== IP Address Seems To Have Changed

	== File descriptor and core file size limits
	== File Descriptor and Core File Size Limits

	For mitigating information, see the article on xref:install:install-splitlock-mitigation.adoc[]
	For more information about how to resolve issues with split lock mitigation, see xref:install:install-splitlock-mitigation.adoc[].

Doc 13694 #4076

Doc 13694 #4076

Uh oh!

Conversation

TimLFletcher commented Jan 22, 2026

Uh oh!

TimLFletcher commented Jan 22, 2026

Uh oh!

sarahlwelton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TimLFletcher commented Jan 26, 2026

Uh oh!

sarahlwelton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarahlwelton left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants