Transparent Huge Pages (THP)

Transparent Huge Pages (THP)

The Transparent Huge Pages (THP) feature of the Linux kernel must be disabled on systems running Couchbase Server.

Huge Pages in Linux-based operating systems create pre-allocated contiguous memory space designed to assist application performance.

Transparent Huge Pages (THP) is a Linux OS feature that conceals much of the complexity of using actual Huge Pages as well as automates the creation of contiguous memory space. It is enabled by default in some Linux Operating systems, but not all.

For most workloads it functions very well, but for databases such as Couchbase it does not. Not only is it not recommended by the OS vendors for databases, but it is detrimental to the performance and function of Couchbase cluster nodes. Such negative influence on the performance is not unique to Couchbase but applies almost to all databases that usually need sparse memory access patterns and rarely have contiguous access patterns.

Turning THP off and keeping it off after reboot is not entirely supported by the Linux OS, and you will have to establish a process that is easy to perform and repeat.

To disable THP follow these steps:

Check the THP status
Check the status of THP by issuing the following commands:
cat /sys/kernel/mm/transparent_hugepage/enabled
cat /sys/kernel/mm/transparent_hugepage/defrag       
On some Red Hat and Red Hat variants, you might have to do this:
cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
cat /sys/kernel/mm/redhat_transparent_hugepage/defrag        
Continue with the procedure described below if in one or both files the output looks as follows:
[always] madvise never
Copy the init script
The init script is designed to make sure that the changes are made around the same time as Couchbase Server is loaded on reboot.
# Provides:          disable-thp
# Required-Start:    $local_fs
# Required-Stop:
# X-Start-Before:    couchbase-server
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Disable THP
# Description:       disables Transparent Huge Pages (THP) on boot
case $1 in
  if [ -d /sys/kernel/mm/transparent_hugepage ]; then
    echo 'never' > /sys/kernel/mm/transparent_hugepage/enabled
    echo 'never' > /sys/kernel/mm/transparent_hugepage/defrag
  elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
    echo 'never' > /sys/kernel/mm/redhat_transparent_hugepage/enabled
    echo 'never' > /sys/kernel/mm/redhat_transparent_hugepage/defrag
    return 0
Register the code in the OS
As root do the following:
  1. Create a file with the above code:
    $ sudo vi /etc/init.d/disable-thp
  2. Chmod the file to be executable:
    $ sudo chmod 755 /etc/init.d/disable-thp
  3. Execute it so it takes effect right now:
    $ sudo service disable-thp start
Make sure the Init script starts at boot
For Red Hat variants:
$ sudo chkconfig disable-thp on       
For Ubuntu:
$ sudo update-rc.d disable-thp defaults
Test the process
Check the status of THP by issuing the following commands:
cat /sys/kernel/mm/transparent_hugepage/enabled
cat /sys/kernel/mm/transparent_hugepage/defrag          
On some Red Hat or Red Hat variants, you might have to do this instead:
cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
cat /sys/kernel/mm/redhat_transparent_hugepage/defrag
For both files, the output should be like this:
always madvise [never]