Management Guide

contents

A.2. Process Configuration Options

In addition to system settings, there are configuration options pertaining to the VoltDB server process itself that can impact performance. Runtime configuration options are set as command line options when starting the VoltDB server process.

The key process configuration for VoltDB is the Java maximum heap size. It is also possible to pass other arguments to the Java Virtual Machine directly.

A.2.1. Maximum Heap Size

The heap size is a parameter associated with the Java runtime environment. Certain portions of the VoltDB server software use the Java heap. In particular, the part of the server that receives and responds to stored procedure requests uses the Java heap.

Depending upon how many transactions your application executes a second, you may need additional heap space. The higher the throughput, the larger the maximum heap needed to avoid running out of memory.

In general, a maximum heap size of a gigabyte (1024) is recommended. More than 2 gigabytes tends to use up space that is needed for data storage without providing any corresponding benefit. Less than 1 gigabyte and there is a risk that Java will run out of memory for throughput-intense applications.

It is important to remember that the heap size is not directly related to data storage capacity. Increasing the maximum heap size does not provide additional data storage space. In fact, quite the opposite. Needlessly increasing the maximum heap size reduces the amount of memory available for storage.

To set the maximum heap size when starting VoltDB, define the environment variable VOLTDB_HEAPSIZE as an integer value (in megabytes) before issuing the voltdb command. For example, the following commands start VoltDB with the recommended 1 gigabyte limit:

$ export VOLTDB_HEAPSIZE="1024"
$ voltdb create host localhost \
         catalog mycatalog.jar deployment deployment.xml

When using the Enterprise Manager, there is an input field on the database configuration dialog for specifying the maximum heap size. The Enterprise Manager uses this value to set both the maximum and the minimum heap size to avoid any issues at runtime should the heap need to grow and additional memory is no longer available.

Note that the Enterprise Manager sets the maximum heap size to the recommended 1024 value by default, as does the voltdb shell command. If you are using the java command line to start VoltDB manually, the default for the maximum heap size is much lower, so use of the java -Xmx argument is strongly recommended.

A.2.2. Other Java Runtime Options (VOLTDB_OPTS)

VoltDB sets the Java options — such as heap size and classpath — that directly impact VoltDB. There are a number of other configuration options available in the Java Virtual machine (JVM).

VoltDB provides a mechanism for passing arbitrary options directly to the JVM. If the environment variable VOLTDB_OPTS is defined, its value is passed as arguments to the Java command line.

  • When starting VoltDB using the voltdb command, the contents of VOLTDB_OPTS are added to the Java command line on the current server.

  • When starting the VoltDB Enterprise Manager, the contents of VOLTDB_OPTS are added to the invocation that the Enterprise Manager uses to start the VoltDB process on all remote servers.

In other words, when starting a cluster manually, you must define VOLTDB_OPTS on each server to have it take effect for all servers. When using the Enterprise Manager, you only need to define VOLTDB_OPTS once, before starting the Enterprise Manager, to have these JVM options take effect on all nodes that the Enterprise Manager starts. For example:

$ cd opt/voltdb/management/
$ export VOLTDB_OPTS="-DmyApp.DebugFlag=true"
$ ./enterprise_manager.sh

Warning

VoltDB does not validate the correctness of the arguments you specify using VOLTDB_OPTS or their appropriateness for use with VoltDB. This feature is intended for experienced users only and should be used with extreme caution.

contents