Memory Management

The graph server (PGX) requires both on-heap and off-heap memory to store graph data.

The allocation of memory for the graph data is as shown:

Default Configuration of Memory Limits

You can configure both on-heap and off-heap memory limits. In case of the on-heap, if you don’t explicitly set a maximum then it will default to the maximum on-heap size determined by Java Hotspot, which is based on various factors, including the total amount of physical memory available.

You can set the max_on_heap_memory_usage_ratio configuration field to decide on the ratio of the total JAVA heap memory that the graph server (PGX) is allowed to use (for example a value of 0.8 would mean that the graph server(PGX) is allowed to use 80% of JAVA heap memory). The default value of this parameter is 1.0 which lets the JVM handle any out of memory errors. It is recommended to set this parameter to 0.9 to avoid the graph server (PGX) from using the full on heap memory as this may cause the server to slowdown or crash.

In case of the off-heap, if you don’t explicitly set a maximum then it will default to the total physical available memory on the machine.

Configuring On-Heap Limits

The on-heap memory limits for the graph server (PGX) can be configured by updating the systemd configuration file for the PGX service. However, there is a risk of losing the updates to the configuration file, the next time you upgrade the graph server (PGX). Therefore, it is recommended that you provide the on-heap memory configuration in a drop-in file. All directives in the drop-in file are dynamically merged with the directives in the main configuration file (/etc/systemd/system/pgx.service) during the graph server (PGX) startup.

Note: The graph server (PGX) periodically checks the on-heap memory size. If the memory usage grows above the threshold defined in the max_on_heap_memory_usage_ratio field (default value is 0.9) in the /etc/oracle/graph/pgx.conf file, then the graph server will throw an exception and cancel the current running task (which is unable to allocate memory). This eliminates the possibility of unexpected server crashes when the heap memory is full. It is recommended that you configure the max_on_heap_memory_usage_ratio option to be less than one, so that the used on-heap memory value remains lesser than the JVM -Xmx value to ensure a safe buffer for heap memory allocation.

You can perform the following steps to create a drop-in file and configure the on-heap memory size:

  1. Navigate to the /etc/systemd/system/pgx.service.d directory. If the pgx.service.d directory does not exist in the file path, then create one.

  2. Create a drop-in file (.conf file) with any name in /etc/systemd/system/pgx.service.d. Skip this step, if one already exists.

  3. Edit the drop-in file as a root user or with sudo command and add the on-heap memory option in the [Service] section as shown:

    sudo vi /etc/systemd/system/pgx.service.d/setup.conf

    The following example displays the added on-heap memory setting in the setup.conf file:

    [Service]
# Java on-heap memory setting
Environment="JAVA_TOOL_OPTIONS=-Xms1G -Xmx2G"

    This option sets the initial heap space to 1GB and allows it to grow up to 2GB.

    The supported options for configuring the on-heap memory are:

    • -Xmx: to set the maximum on-heap size of the JVM.

    • -Xms: to set the initial on-heap size of the JVM.

    • -XX:NewSize: to set the initial size of the young generation

    • -XX:MaxNewSize: to set the maximum size of the young generation

    See the java command documentation for more information on these options.

  4. Add the JAVA_HOME environment variable to ensure that the graph server (PGX) is using the appropriate JDK.

    [Service]
# JAVA_HOME variable
Environment=JAVA_HOME=/usr/java/jdk-15.0.1/
# Java on-heap memory setting
Environment="JAVA_TOOL_OPTIONS=-Xms1G -Xmx2G"

    Note that the comments begin with # and you can optionally comment any specific option in order to test your configuration.

  5. Reload the PGX service to use the updated settings by running the following command:

    sudo systemctl daemon-reload

  6. Restart the graph server (PGX):

    sudo systemctl restart pgx

  7. Verify that the service restarted with the new memory settings:

    systemctl status pgx

    You may see a similar output:

    ● pgx.service - Oracle Graph In-Memory Server
   Loaded: loaded (/etc/systemd/system/pgx.service; enabled; vendor preset: disabled)

  Drop-In: /etc/systemd/system/pgx.service.d
           └─setup.conf
   Active: active (running) since Wed 2023-04-12 14:50:49 CEST; 5 days ago
 Main PID: 1209 (bash)
   CGroup: /system.slice/pgx.service
           ├─1209 /bin/bash start-server
           └─1469 /usr/java/jdk-11.0.6/bin/java -Dlogback.configurationFile=/etc/oracle/graph/logback-server.xml

                    -Doracle.jdbc.fanEnabled=false -cp /opt/oracle/graph/pgx/bin/../../pgx/server/lib/activatio...

    Review the Drop-In unit file as shown highlighted in the preceding output. This confirms that systemd found the drop-in file and applied the required customizations.

  8. Finally, use the server-state REST endpoint to confirm the new memory usage. For example:

    BASE_URL=https://localhost:7007
USERNAME=graph
PASSWORD=graph
PGX_RESPONSE=`curl -s -k -X POST -H 'Content-Type: application/json' -d '{"username": "'"${USERNAME}"'", "password": "'"${PASSWORD}"'"}' ${BASE_URL}/auth/token`
PGX_ACCESS_TOKEN=`echo $PGX_RESPONSE | jq -r '.access_token'`
curl -s -k -H 'Authorization: Bearer '"${PGX_ACCESS_TOKEN}" $BASE_URL/control/v1/serverState|jq '.entity.memory'

    Note that the preceding example uses the jq tool to fetch and format the output.

Configuring Off-Heap Limits

You can specify the off-heap limit by setting the max_off_heap_size field in the graph server (PGX) configuration. See Configuration Parameters for the Graph Server (PGX) Engine for more information on the max_off_heap_size parameter. Note that the off-heap limit is not guaranteed to never be exceeded because of rounding and synchronization trade-offs.