Disabling 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.

#!/bin/bash
### BEGIN INIT INFO
# 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
### END INIT INFO

case $1 in
start)
  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
  else
    return 0
  fi
;;
esac

Register the code in the OS

As root do the following:

Create a file with the above code:
```
# vi /etc/init.d/disable-thp
```
Chmod the file to be executable:
```
# chmod 755 /etc/init.d/disable-thp
```

Execute it so that it takes effect right now:

# service disable-thp start

If you encounter an error running the script, you can run the commands manually as follows:

# echo never > /sys/kernel/mm/transparent_hugepage/enabled
# echo never > /sys/kernel/mm/transparent_hugepage/defrag{{}}

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 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]