1. Administering Oracle Unified Directory
  2. Advanced Administration: Monitoring and Tuning Performance
  3. Tuning Performance

36 Tuning Performance

Oracle Unified Directory aims to be high-performing and highly-scalable. Though the server can achieve impressive results with the default server configuration and JVM settings, you can often significantly improve performance through some basic tuning.

The default settings of Oracle Unified Directory are targeted at evaluators and developers who run equipment with limited resources. When you deploy Oracle Unified Directory in a production environment, it useful to do some initial tuning of the Java Virtual Machine (JVM) and of the server configuration to improve scalability and performance (particularly for write operations).

Topics:

36.1 About Performance Problem Assessment

Examine the access log at INSTANCE_DIR/OUD/logs/access to get a quick idea of whether performance issues are related to problems with the server or with the client.

This log contains entries of the form:

[09/Sep/2009:15:36:18 +0200] SEARCH RES conn=1 op=16 msgID=17 
  result=0 nentries=1 etime=1

The value of the etime field is the time (in milliseconds) that the server spent processing the request. Large etimes generally indicate an issue on the server side (which can usually be resolved by appropriate performance tuning or indexing). If you are experiencing performance problems but the etimes are small, the issue is more likely to be with your client application.

Comprehensive monitoring information is available under the cn=monitor entry. See Monitoring Oracle Unified Directory. You can also use Oracle Enterprise Manager to monitor Oracle Unified Directory performance. Refer to Viewing Performance Metrics for an OUD Instance in Oracle® Enterprise Manager Plug-in forOracle Unified Directory User's Guide.

36.2 Understanding How to Tune General Performance Parameters

Performance tuning strategies differ, depending on whether you run a directory server or a proxy server.

The following parameters can improve performance in specific deployment scenarios:

  • Java Version. Use the most recent Java Runtime Environment (JRE) release available. Oracle Unified Directory works with Java 8 Update 131+.

  • Environment Variables. The server uses the OPENDS_JAVA_HOME environment variable to point to your installed JRE. If you have multiple versions of Java installed on a system, set the JAVA_HOME environment variable to point to the root of the desired installation. In this way, the version of the JRE specified by the JAVA_HOME variable can be used by other applications but not by Oracle Unified Directory.

    To specify a JRE installation for the server, do one of the following:

    • Use the dsjavaproperties command to set the appropriate environment variables.

      For more information, see dsjavaproperties.

    • Set the OPENDS_JAVA_BIN environment variable (with the JAVA binary path).

    • Set the OPENDS_JAVA_HOME environment variable (with the JAVA installation path).

36.3 Understanding Java Virtual Machine Settings Using dsjavaproperties Utility

You can use the JAVA_ARGS environment variable to provide global configuration arguments that can be passed to the JVM, or you can use the java.properties file. Any argument that can be used with the java command can be used with both methods.

It is recommended to tune the JVM for optimal performance and ensures that Oracle Unified Directory applications are robust and responsive. You can tune the JVM by tuning the heap size. The heap size is divided into the following:

  • Young generation: Includes operations like PDUs and local variables.

  • Old generation: Includes Oracle Unified Directory caches like the JE database cache and the entry cache.

  • Permanent generation: Includes constants and classes.

When Oracle Unified Directory is in Directory Server mode, you can perform one of the following database caching options:

  • Cache the entire database in database cache. This will give optimal performance but will lead to long cache warmup and larger heap size.

  • Cache only the internal nodes of the database Btree (Upper and inner nodes) in database cache and keep remaining RAM for file system cache. This will give good performance, short cache warmup, smaller heap size and is recommended for very large deployments (Above 50MBytes entries). It is recommended for small and medium deployments.

For more information, see Determining the Database Cache Size.

Note:

For proxy mode, use large old generation for distribution with global index.

For more information, see dsjavaproperties.

For additional information about tuning the JVM, see the Java Performance Documentation (http://java.sun.com/docs/performance/).

The Java Tuning White Paper and Garbage Collection Tuning documents, both at http://www.oracle.com/technetwork/java/performance-138178.html, are also particularly useful.

The following table describes the main JVM tunable options:

Parameter Description

-server

Always use the server JVM instead of the client JVM. The client VM is better optimized for processes that run for a short period of time and need to start as quickly as possible. The server VM can take longer to warm up but is faster in the long run.

-d32 or -d64

Select the 32-bit or 64-bit version of the JVM as follows:

  • -d32 provides better performance for JVM heaps smaller than 3.5Gbytes.

  • -XX:+UseCompressedOops should be used for JVM heaps between 3.5Gbytes and 31Gbytes.

  • -d64: should be used for JVM heaps over 32Gbytes.

-XX:+UseCompressedOops

Use this option if you use the 64-bit JVM and if the heap size is less than 32 Gbytes.

-Xms2g and -Xmx2g

This parameter sets the initial and maximum heap size available to the JVM. Increasing the heap size can improve performance, but setting it too high can have a detrimental effect in the form of longer pauses for full garbage collection runs. The initial and maximum sizes should generally be set to the same values.

For maximum performance, size the heap so that the entire DB can be cached in memory. In general, you should allocate enough heap for the server runtime and the rest to the DB cache.

For example, if you want to modify the heap size of an Oracle Unified Directory instance with only one JE back end named userRoot. Then you must decide the space needed for the new generation, the old generation and the perm generation. To size the different generations, you must consider the following:

  • The size of the database impacting the old generation

  • Determine the need to use an entry cache impacting the old generation.

  • The type of GC used impacting the old generation.

  • The type of usage impacting the new generation.

If you use CMS as the garbage collector of the oldgen, then you must consider the -XX:CMSInitiatingOccupancyFraction property when calculating the heap size so that it is coherent with the size (or percent of the heap) occupied by the dbcache.

If you set the CMSInitiatingOccupancyFraction to 55, then set the dbcache percent to 50. Then, if you have a database on disk that is 10GB, you need at least a heap of 22GB for the entire database to fit into the dbcache.

-XX:NewSize=512M

The total heap space is divided into the old generation and the young generation. This parameter sets the size of the young generation. The remaining memory (old generation) must be sufficient to hold the DB cache plus some overhead.

-XX:+UseConcMarkSweepGC

Use the Concurrent Mark Sweep (CMS) garbage collector. This option allows the JVM to minimize the response time of LDAP operations, but it can have a small impact on the overall performance (throughput) of the server. Use this option of long pause times are not tolerated.

-XX:CMSInitiatingOccupancyFraction= <percentage>

Specify the level at which the CMS garbage collection is started. The default value is approximately 68%. Use this value if you want to set the percentage to something other than the default value.

-XX:+UseBiasedLocking

Improve locking performance in the server in cases where there is not expected to be a high degree of contention.

-XX:LargePageSizeInBytes=256m

Use large pages for the information it stores in memory. This argument applies primarily to systems using the UltraSPARC T1 processor.

-XX:+UseParallelGC

Specify that the system should use parallel garbage collection, which is particularly useful on systems with a large number of CPUs.

-XX:+UseParallelOldGC

Specify that the JVM should use parallel garbage collection for the old (tenured) generation.

-XX:ParallelGCThreads=8

Specify that the JVM should use 8 threads when performing parallel garbage collection. By default, the number of threads equals the number of CPUs, but this can be inappropriate on systems with a very large number of CPUs or on CMT-based systems like those using the UltraSPARC T1 processor.

36.4 Tuning Java Virtual Machine Settings Using the dstune Utility

The dstune command-line utility allows you to tune the Oracle Unified Directory server and tools (import-ldif, export-ldif, rebuild-index, and verify-index) using criteria such as the data that the directory contains or the amount of system memory to use.

Any changes made using the dstune utility take effect when the server is restarted.

This section includes the following topics:

Note:

The various tuning options, described in Understanding the Tuning Options Provided by the dstune Utility, are available only if you run a Java Virtual Machine that uses Java HotSpot, such as the Oracle Java Standard Edition. If you run a JVM without Java Hotspot, the dstune memory-based and data-based options are not available.

36.4.1 Using the dstune Utility

The dstune utility has several tuning options. You can tune the Oracle Unified Directory server based on memory limits or LDAP data information or by providing runtime options.

The following topics describe the different tuning options available using the dstune utility:

36.4.1.1 Understanding the Tuning Options Provided by the dstune Utility

Note:

Beginning with Oracle Unified Directory11g Release 2 (11.1.2.3), the dstune automatic subcommand is no longer available (but automatic usage is still available for backward compatibility).

To specify automatic tuning similar to previous versions of Oracle Unified Directory, use the dstune set-runtime-options subcommand with the --value autotune suboption. See About Runtime Tuning.

For more information about the dstune subcommands and options, see dstune

The dstune utility allows you to tune the server and tools based on the following tuning options:

36.4.1.1.1 About Data-Based Tuning

The data-based tuning mode (dstune data-based subcommand) allows you to tune the Oracle Unified Directory server based on the data that the contents of the database will contain or currently contains.

To provide information about the data that the database will contain, specify the number of entries (--entryNumber suboption) and the average size in kilobytes of the entries (--entrySize suboption).

You can also specify a path to an LDIF file (-l or --ldifFile suboption) that contains the data to tune the server.

If you do not provide options or the information about the data that the database will contain, the data-based subcommand analyzes the contents of the current database and determines the recommended minimum and optimal memory values for that data.

In non-interactive mode, dstune uses a default memory value to tune the server (and displays the memory value used).

In interactive mode, dstune asks you for a memory value, but it also presents some recommendations.

36.4.1.1.2 About Memory-Based Tuning

The memory-based tuning mode (dstune mem-based subcommand) allows you to tune the Oracle Unified Directory server and tools based on the heap size they will use.

To specify the memory to be used for the server or tools, use the --memory heap-size suboption.

If you are tuning the server, you can specify the system memory (systemMemory option) as either an amount or percentage:

  • Amount: For example, to use 2 GB, specify systemMemory:2g. The dstune utility then splits the value you provide into two parts: the heap size that the Java Virtual Machine of the server will use and an estimation of the required file-system cache.

  • Percentage: For example, to dedicate 50 percent of system memory to the server, specify systemMemory:50.0%. To fully dedicate a machine to the server, specify systemMemory:100%.

By default, dstune tunes the server, but the --targetTool option allows you to specify the other tools to tune.

36.4.1.1.3 About Runtime Tuning

The runtime tuning mode (dstune set-runtime-options subcommand) allows you to use the JVM default values on the system or to directly provide JVM arguments to tune the Oracle Unified Directory server and tools.

The automatic tuning mode (--value autotune suboption) also allows you to tune the server and each tool automatically each time they are launched.

By default, dstune tunes the server, but the --targetTool option allows you to specify the tools you want to tune.

36.4.1.2 Displaying the Current Tuning Mode

You use the dstune list subcommand to display the current tuning settings of an Oracle Unified Directory server and the tools.

For example, the following command displays the current tuning settings of an Oracle Directory Server instance and tools.

$ dstune list

Tool          : Tuning Value
--------------:-------------------------------------------------------------------
server        : -Xms853m -Xmx853m -d32 -server -XX:MaxTenuringThreshold=1
              : -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=55
import-ldif   : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
export-ldif   : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
rebuild-index : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
verify-index  : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA

36.4.2 Executing the Interactive Mode of the dstune Utility

The interactive mode of the dstune utility provides the capability to tune Oracle Unified Directory and tools server based on memory limits or LDAP data information or by providing runtime options.

Note:

For more information about the tuning options, see Understanding the Tuning Options Provided by the dstune Utility.

36.4.2.1 Setting Memory-Based Tuning Options

You use the interactive mode of the dstune utility to tune Oracle Unified Directory server using memory-based tuning options.

This section contains the following topics:

36.4.2.1.1 Tuning Oracle Unified Directory Server by Specifying a Heap Size

The example in this section describes how to run the dstune utility in interactive mode to tune Oracle Unified Directory server by specifying 2 Gbytes for the heap size.

Run the dstune utility as follows: 

$ dstune 
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 1
 
You must provide the tools the runtime options will apply to.
If you want to use the settings for the server, provide the value 'server'.
If you want to use the settings for all the tools, provide the value 'all'.
The other allowed values are import-ldif, export-ldif, rebuild-index,
verify-index.
You can provide several values separated with a comma (for instance
'export-ldif,rebuild-index').
 
Tools [server]: 
 
You have chosen to tune the server.  To tune the server you can provide
directly the Java heap size to be used by the server, you can specify the
amount of system memory to be used providing a percentage (use 100 % to
dedicate the machine to the OUD server) or you can specify the amount of
system memory (the sum of the Java Heap and an estimation of the required File
System Cache).
 
    1)  Provide the heap size
    2)  Provide the percentage of system memory to be used by the server
    3)  Provide the size of system memory to be used by the server
 
Enter choice [1]: 
 
You must provide the heap size to be used by the tools.
To specify a value in megabytes, use 'm' after the value (for instance 768m).
For gigabytes, use 'g' (for instance 2.5g).
If no unit is specified after the value, megabytes will be used.
 
Heap Size [2.27g]: 2g
 
Calculating Tuning Settings ..... Done.
Updating the tuning properties ..... Done.
Updating scripts ..... Done.
36.4.2.1.2 Tuning Oracle Unified Directory Server by Specifying a Percentage of System Memory

The example in this section describes how to run the dstune utility in interactive mode to tune Oracle Unified Directory server by specifying 50 percent of system memory to be used by the server. The server has 100,000 entries.

Run the dstune utility as follows: 

$ dstune
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 1
 
You must provide the tools the runtime options will apply to.
If you want to use the settings for the server, provide the value 'server'.
If you want to use the settings for all the tools, provide the value 'all'.
The other allowed values are import-ldif, export-ldif, rebuild-index,
verify-index.
You can provide several values separated with a comma (for instance
'export-ldif,rebuild-index').
 
Tools [server]: 
 
You have chosen to tune the server.  To tune the server you can provide
directly the Java heap size to be used by the server, you can specify the
amount of system memory to be used providing a percentage (use 100 % to
dedicate the machine to the OUD server) or you can specify the amount of
system memory (the sum of the Java Heap and an estimation of the required File
System Cache).
 
    1)  Provide the heap size
    2)  Provide the percentage of system memory to be used by the server
    3)  Provide the size of system memory to be used by the server
 
Enter choice [1]: 2
 
To be able to properly calculate the Java heap size for a given percentage,
the contents of the database will be analyzed.
 
Reading the Server Configuration ..... Done.
Reading the Database Contents ..... Done.
 
The memory you assign for OUD will be divided in two parts: the Java heap size
of the OUD process and the estimated memory that will be required for the file
system cache.
Provide the percentage of the memory that should be assigned to OUD (use 100%
if you want to have a dedicated machine for this OUD server).
 
Memory Percentage [25.73]: 50
 
The specified percentage corresponds to the following memory values:
2.83 GB: 1.59 GB (OUD Java Heap Size) + 1.25 GB (Estimated File System Cache)
Do you want to use this value? (yes / no) [yes]: 
 
Calculating Tuning Settings ..... Done.
Updating the tuning properties ..... Done.
Updating scripts ..... Done.
36.4.2.2 Setting Data-Based Tuning Options

You use the interactive mode of the dstune utility to tune Oracle Unified Directory server using database-based tuning.

This section contains the following topics:

36.4.2.2.1 Tuning Oracle Unified Directory Server Using the Contents of the Database

The example in this section describes how to run the dstune utility in interactive mode to tune Oracle Unified Directory server using the data that the server currently contains (that is, the current contents of the database).

Run the dstune utility as follows: 

$ dstune
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 2
Provide information about the LDAP data that will be used to tune the server.
You can choose to tune the server based on its current contents, you can
provide an LDIF File with the data, or directly the number and average size of
your entries.
 
    1)  Use the data that the server contains currently
    2)  Use the contents of an LDIF file
    3)  Use the number of entries 
 
    c)  cancel
 
Enter choice [1]: 
 
To calculate the tuning options, the contents of the database will be
analyzed.
 
Reading the Server Configuration ..... Done.
Reading the Database Contents ..... Done.
 
Memory Requirements Information for the Data in the Server:
 
System Memory:                   5.66 GB
Recommended Min. Memory:         444.76 MB (7.67 % of System Memory)
                                 288.73 MB (Java Heap) +  156.04 MB (Estimated
                                 File System Cache)
Memory for Optimal Performance:  1.46 GB (25.73 % of System Memory)
                                 1.30 GB (Java Heap) +  0.15 GB (Estimated File
                                 System Cache)
================================================================================
Recommended Memory:              1.46 GB (25.73 % of System Memory)
                                 1.30 GB (Java Heap) +  0.15 GB (Estimated File
                                 System Cache)
 
You must provide the memory you want to use.  You can provide the Java heap,
the amount of system memory or the percentage of the system memory that you
want the OUD server to use.
 
    1)  Provide the heap size
    2)  Provide the percentage of system memory to be used by the server
    3)  Provide the size of system memory to be used by the server
 
Enter choice [1]: 
 
You must provide the heap size to be used by the tools.
To specify a value in megabytes, use 'm' after the value (for instance 768m).
For gigabytes, use 'g' (for instance 2.5g).
If no unit is specified after the value, megabytes will be used.
 
Heap Size [1.30g]: 
 
Updating the tuning properties ..... Done.
Updating scripts ..... Done.
36.4.2.2.2 Tuning Oracle Unified Directory Server by Providing an LDIF File

The example in this section describes how to run the dstune utility in interactive mode to tune Oracle Unified Directory server by providing an LDIF file with 200,000 entries.

Run the dstune utility as follows: 

$ dstune
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 2
Provide information about the LDAP data that will be used to tune the server.
You can choose to tune the server based on its current contents, you can
provide an LDIF File with the data, or directly the number and average size of
your entries.
 
    1)  Use the data that the server contains currently
    2)  Use the contents of an LDIF file
    3)  Use the number of entries 
 
    c)  cancel
 
Enter choice [1]: 2
 
LDIF File Path: /tmp/example.ldif
Calculating tuning settings based on the contents of the LDIF file ..... Done.
 
Analyzing file /scratch/joverga/servers/example.ldif (around 2 seconds
remaining) ..... Done.
 
Memory Requirements Information for the LDIF File:
 
System Memory:                   5.66 GB
Recommended Min. Memory:         550.79 MB (9.50 % of System Memory)
                                 321.46 MB (Java Heap) +  229.33 MB (Estimated
                                 File System Cache)
Memory for Optimal Performance:  1.67 GB (29.52 % of System Memory)
                                 1.45 GB (Java Heap) +  0.22 GB (Estimated File
                                 System Cache)
================================================================================
Recommended Memory:              1.67 GB (29.52 % of System Memory)
                                 1.45 GB (Java Heap) +  0.22 GB (Estimated File
                                 System Cache)
 
You must provide the memory you want to use.  You can provide the Java heap,
the amount of system memory or the percentage of the system memory that you
want the OUD server to use.
 
    1)  Provide the heap size
    2)  Provide the percentage of system memory to be used by the server
    3)  Provide the size of system memory to be used by the server
 
Enter choice [1]: 
 
You must provide the heap size to be used by the tools.
To specify a value in megabytes, use 'm' after the value (for instance 768m).
For gigabytes, use 'g' (for instance 2.5g).
If no unit is specified after the value, megabytes will be used.
 
Heap Size [1.45g]: 
 
Updating the tuning properties ..... Done.
Updating scripts ..... Done.
36.4.2.3 Setting Runtime Tuning Options

You use the interactive mode of the dstune utility to set the runtime tuning options for the server and tools.

The example in this section sets the JVM options for the server and the export-ldif tool.

To tune the Oracle Unified Directory Server using the JVM Options, run the dstune utility as follows: 

$ dstune
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 3
 
You must provide the tools the runtime options will apply to.
If you want to use the settings for the server, provide the value 'server'.
If you want to use the settings for all the tools, provide the value 'all'.
The other allowed values are import-ldif, export-ldif, rebuild-index,
verify-index.
You can provide several values separated with a comma (for instance
'export-ldif,rebuild-index').
 
Tools [server]: server,export-ldif
 
You must provide the runtime options you want to use.
If you want to use automatic tune, provide the value 'autotune'.
If you want to use the default settings of the Java Virtual Machine on your
system, provide the value 'jvm-default'.
You can also provide directly the Java arguments that the tools must use.
 
Runtime Options [autotune]: -server -Xmx2048m
 
Updating the tuning properties ..... Done.
Updating scripts ..... Done.
36.4.2.4 Displaying the Current Tuning Settings

The example in this section runs the dstune utility in interactive mode to display the current tuning settings of an Oracle Unified Directory server and tools.

Run the dstune utility as follows: 

$ dstune
What do you want to do?
 
    1)  Tune based on memory limits
    2)  Tune based on LDAP data information
    3)  Tune providing runtime options
    4)  List the current tuning settings
 
    q)  quit
 
Enter choice: 4
 
Tool          : Tuning Value
--------------:-------------------------------------------------------------------
server        : -Xms853m -Xmx853m -d32 -server -XX:MaxTenuringThreshold=1
              : -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=55
import-ldif   : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
export-ldif   : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
rebuild-index : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA
verify-index  : -Xms715m -Xmx715m -d32 -server -XX:+UseParallelGC -XX:+UseNUMA

36.5 Determining the Database Cache Size

If you have installed or configured and initialized an Oracle Unified Directory instance then you can determine the database cache size requirements by measuring the size of <OUD_INSTANCE_DIR>/OUD/db/userRoot directory (Assuming there is only one database for the Oracle Unified Directory instance named userRoot).

If an Oracle Unified Directory instance is not configured or initialized, then you can determine the memory required to store internal nodes for one index file or the file containing user data, by running the DbCacheSize utility (com.sleepycat.je.util).

For more information on using the DbCacheSize utility, see this Javadoc page: http://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/util/DbCacheSize.html.

For example, 10 million entries of 4Kbytes with an index and average key size of 10 bytes are as follows:

[oud@oel5 bin]$ java -jar -XX:+UseCompressedOops /space/Middleware/
Oracle_OUD1/lib/je.jar DbCacheSize -records 10000000 -key 10 -data 4000
 
=== Database Cache Size ===
 Minimum Bytes    Maximum Bytes   Description
---------------  ---------------  -----------
    259,725,752      317,907,896  Internal nodes only
 40,721,011,192   40,779,193,336  Internal nodes and leaf nodes
=== Internal Node Usage by Btree Level ===
 Minimum Bytes    Maximum Bytes      Nodes    Level
---------------  ---------------  ----------  -----
    256,180,800      313,709,120     112,360    1
      3,503,312        4,149,456       1,262    2
         38,864           46,032          14    3
          2,776            3,288           1    4

A 10 million entries deployment with 4 Kbytes will require 37 Gbytes to store the full user data in the database cache (4Kbytes entries and the internal nodes of the Database Btree). If you want to store only the internal nodes in the database cache, then 303 Mbytes are required per indexes (3 Gbytes for 10 indexes).

36.6 Tuning the Server Configuration

Various components of the server can be tuned to provide performance improvements in specific scenarios. Most performance tuning recommendations depend on several variables, including the anticipated workload, the types of data that are stored, and the hardware and resources available.

The following topics provide some general tuning recommendations for performance improvement in specific deployments:

36.6.1 Back End Tuning Parameters

Review this topic for the different Berkeley DB JE parameters to tune performance improvements of the Berkeley Database.

The following table lists these parameters to tune performance:

Parameter Description

je.checkpointer.highPriority

If true, the checkpointer uses more resources to complete the checkpoint in a shorter time interval. Btree latches are held and other threads are blocked for a longer period. Log cleaner record migration is performed by cleaner threads instead of lazily during eviction and checkpoints (see CLEANER_LAZY_MIGRATION). When set to true, application response time may be longer during a checkpoint, and more cleaner threads may be required to maintain the configured log utilization.

Setting that property to false is a way to achieve better throughput and lower response times.

preload-time-limit

You can configure the server to preload some database contents into memory on startup. For large databases, preloading the database cache avoids a long warmup period after server startup. For more information, see "Local DB Backend Configuration" in the Configuration Reference for Oracle Unified Directory.

db-cache-percent and

db-cache-size

Use these properties to configure the amount of memory that the database cache uses. For best performance, consider configuring the server so that the whole database fits into the database cache.

Determine the approximate size of the database after an import. For example, after doing an import into the userRoot back end, run the following command (on UNIX systems) to determine the size of the database: 

$ cd INSTANCE_DIR/OUD/db
$ du -sk userRoot/
910616 userRoot/

On Windows systems, use an equivalent procedure to determine the database size. Remember that the database size is not static and can increase after an initial import when modifications are made.

Setting the JVM heap to 2 Gbytes (-Xms2g -Xmx2g), and the db-cache-percent to 50, will cause the DB cache to use 1 Gbyte of memory. To monitor the DB cache size, observe the following properties under the "dn:cn=userRoot Database Environment,cn=monitor" entry through Jtrace and JMX:

  • Check that EnvironmentCacheDataBytes has a value that is consistent with the expected size of the DB cache.

  • Check that EnvironmentNCacheMiss does not have unexpected growth when loading the server.

As the database grows very large over time due to replication metadata, users, and applications. This may effect the performance after the import. It is recommended that you tune the Oracle Unified Directory JVM heap size (Primarily the old generation).

db-directory

Ensure that the database is held on a fast file system with adequate storage. The file system should be different to the location of the access logs. By default, the database will grow to twice its original size. For example, if the database is 1 Gbyte after an import, the file system should have at least 2 Gbytes available.

db-evictor-lru-only

Use this property can be used to control how the database cache retains information. Setting this value to false ensures that the internal nodes are maintained in cache, which provides better performance when the JE cache holds only a small percentage of the database contents.

db-txn-durability

Use this property to configure durability for write operations. Reducing durability can increase write performance, but it can also increase the chance of data loss if your JVM or system crashes. This property takes the following values:

  • write-to-disk. All data are written synchronously to disk.

  • write-to-filesystem. Data are written to the file system immediately, but might stay in the file system before being flushed to disk.

  • write-to-cache. Data are written to an internal buffer and flushed to the file system, then to disk when necessary.

db-log-file-max

Use this property to control the size of JE log files. Increasing the file size can improve write performance, but it can also make it harder to maintain the desired utilization percentage.

db-num-cleaner-threads and db-cleaner-min-utilization

These properties control how the cleaner works, which keeps the database size down and keeps up with high write throughput.

db-num-lock-tables

On systems with a large number of CPUs, this property can improve concurrency within the database lock manager.

36.6.2 Core Server Tuning Parameters

Review this topic for the different parameters to tune performance improvements of the core server.

The following table lists the following core server tuning parameters to tune performance:

Parameter Description

num-request-handlers

You can configure this property to enable the LDAP connection handler (and the LDAPS connection handler, if it is enabled) to use multiple threads for decoding client requests. Increasing the number of threads on systems with a larger number of CPUs can improve performance. As a rule of thumb, set this property to a quarter the number of CPUs, with a maximum of twelve.

In some cases, disabling the keep-stats property can help reduce lock contention in the connection handlers. For more information, see "LDAP Connection Handler Configuration" in the Configuration Reference for Oracle Unified Directory.

num-worker-threads

The default value of this property is two times the number of CPUs, which is sufficient in most deployments.

log-file

Ensure that the access log publisher is on a fast file system, or turn it off altogether by setting the enabled property to false. For more information see "File Based Access Log Publisher Configuration" in the Configuration Reference for Oracle Unified Directory.

36.6.3 Tuning a Server Containing Static Groups

Review these topics for some recommendations on performance improvement if your server contains static groups.

36.6.3.1 Enabling a FIFO Group Entry Cache

You can improve the overall performance of the server by storing static groups in a FIFO Group Entry Cache. Storing static groups in this cache reduces the time required to perform group membership lookup, which is necessary in evaluating ACIs for example.

Note:

For more information, see "FIFO Group Entry Cache Configuration" in the Configuration Reference for Oracle Unified Directory.

For example, to create a new FIFO Group Entry cache using dsconfig, run the following command: 

$ ./dsconfig create-entry-cache -t fifo-group --cache-name myGroupCache \
--set cache-level:1 --set enabled:true -n

To list properties of this FIFO Group Entry cache using dsconfig, run the following command: 

$ ./dsconfig get-entry-cache-prop --cache-name myGroupCache
Property           : Value(s)
-------------------:-----------------------------------------------------------
cache-level        : 1
enabled            : true
exclude-filter     : (objectClass=ds-virtual-static-group)
include-filter     : (|(objectClass=groupOfNames)(objectClass=groupOfUniqueName
                   : s)(objectClass=groupOfEntries))
max-entries        : 2147483647
max-memory-percent : 5
36.6.3.2 Configuring FIFO Group Entry Cache Properties

Oracle Unified Directory supports several kinds of cache to enhance the performance especially of the database cache and the file system cache. FIFO Group Entry Caches use a FIFO queue to keep track of the cached entries. They are designed to cache large static group entries.

In deployment scenarios involving large static groups, you can configure the entry cache to include the group entries to accelerate group membership and group-based ACI evaluation. To do so, you can configure the following properties:

  • include-filter: Specifies a set of filters to define criteria for determining which entries should reside in the entry cache. If a filter list is provided, then only entries matching at least one of the given filters is stored in the cache.

    For instance, entries matching the following LDAP criteria will be stored in the entry cache:

    “(|(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)(objectClass=groupOfEntries))”

    You can also split the preceding filter as follows:

    Default:

    (|(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)(objectClass=groupOfEntries))

    After splitting:

    ds-cfg-include-filter: (objectClass=groupOfNames)
ds-cfg-include-filter: (objectClass=groupOfUniqueNames)
ds-cfg-include-filter: (objectClass=groupOfEntries)

    The Default and the After behavior is the same. In both the scenarios, if any one of the filter matches, then it adds that entry in the group cache.

    It is worth mentioning that if ds-cfg-include-filter property is not provided, then it will return the all the static groups.

  • cache-level: Specifies the cache level in the cache order in which the cache will be configured or processed if more than one instance of the cache is configured.

    By default, the cache-level is set to 1 for FIFO Group Cache. However, if you want to define a different cache type, for instance Soft Reference or File System Entry cache then you must provide a different value for cache-level property. In other words, the cache-level should not be the same as defined for FIFO Group Cache as 1. You must define the cache level as more than one.

36.6.3.3 Evaluating Member or Uniquemember Indexes

Evaluation of group membership (ismemberof attribute, ACIs) is using the member and uniquemember indexes. To improve server performance, it is recommended that you set the index-entry-limit property for these indexes to a value that is greater than the maximum number of groups to which a user can belong.

Note:

For more information, see "Local DB Index" in the Configuration Reference for Oracle Unified Directory.

For example, to set the index-entry-limit property of the member index to 5,000 using dsconfig, run the following command: 

$ ./dsconfig set-local-db-index-prop --element-name userRoot --index-name member --set index-entry-limit:5000

After setting the index-entry-limit property, it is recommended that you rebuild the index. For example, 

$ rebuild-index -b dc=example,dc=com -i member

Note:

For more information, see Maintaining Indexes.

To list properties of the member index using dsconfig, run the following command: 

 $ ./dsconfig get-local-db-index-prop --element-name userRoot --index-name member
 Property                       : Value(s)
 -------------------------------:---------
 attribute                      : member
 index-entry-limit              : 5000
 index-extensible-matching-rule : -
 index-type                     : equality
36.6.3.4 Managing Static Groups With More Than 100,000 Members

You can manage static groups by defining some limits for the following operations:

  • MOD, MODDN, and DEL operations on static groups:

    If the operation exits with an administrative limit exceeded error, then you can increase the server's member-lookthrough-limit property value.

  • SEARCH operations on groups:

    An ASN.1 error occurs when a SEARCH operation returns a static group entry containing more than 100,000 members. You can increase the maximum number of returned members by changing the server's returned-attribute-value-limit property.

When increasing these various limits, you must tune the allocated memory for the Java Virtual Machine accordingly.

Note:

For more information about the preceding operations, see "Global Configuration" in the Configuration Reference for Oracle Unified Directory.

Following are some examples:

  • To set the member-lookthrough-limit property to 200,000 using dsconfig, run the following command: 

    $ ./dsconfig set-global-configuration-prop --advanced --set member-lookthrough-limit:200000

  • To set the returned-attribute-value-limit property to 150,000 using dsconfig, run the following command: 

    $ ./dsconfig set-global-configuration-prop --advanced --set returned-attribute-value-limit:150000

  • To retrieve the value of these properties using dsconfig, run the following command: 

     $ ./dsconfig get-global-configuration-prop --advanced 
--property returned-attribute-value-limit --property member-lookthrough-limit
 Property                       : Value(s)
 -------------------------------:---------
 member-lookthrough-limit       : 200000
 returned-attribute-value-limit : 150000
36.6.3.5 Importing Static Groups

Oracle Unified Directory has introduced a new server-wide configuration parameter, import-big-entries-memory-percent, to allow importing big entries like big group entries.

The following topics describe how to import static groups:

36.6.3.5.1 Overview of Importing Static Groups

Whether you perform the import online or offline, import-big-entries-memory-percent represents the amount of memory that the JVM will allocate to allow big entries, such as big group entries to be loaded into memory after they have been read from the imported LDIF file, so that they fit into memory.

  • For offline imports, the JVM performing the import is the import-ldif command JVM.

  • For online imports,Oracle Unified Directory creates an administrative import task in the JVM of the server and the import is performed inside the server's JVM.

When the import is launched, a certain amount of memory is available in the considered process. (Some memory has already been reserved for other components, such as the DB cache.) The import-big-entries-memory-percent represents what percentage of this free memory will be reserved to enable big entries from the LDIF file to load. The import machinery uses the rest of the memory.

The default import-big-entries-memory-percent value is 10%. If you import LDIF files with big group entries (for example, millions of members), and if the JVM is running out of memory, it would be worse if you increased the percentage value to something like 80-90%.

If you run out of memory when importing big groups entries, then you should tune the import-big-entries-memory-percent parameter, but you should also consider increasing the JVM heap size, tuning java.properties, and running the dsjavaproperties command afterward.

Note:

For more information, see "Global Configuration" in the Configuration Reference for Oracle Unified Directory.

36.6.3.5.2 Setting the Configuration Parameter for Importing Static Groups

You use the import-big-entries-memory-percent property for setting the configuration parameter for large static groups.

For example, to set the import-big-entries-memory-percent property to 20% using dsconfig, run the following command: 

$ ./dsconfig set-global-configuration-prop --set import-big-entries-memory-percent:20

To retrieve the value of the import-big-entries-memory-percent property using dsconfig, run the following command: 

$ ./dsconfig get-global-configuration-prop --property import-big-entries-memory-percent
 Property                          : Value(s)
 ----------------------------------:---------
 import-big-entries-memory-percent : 20

36.6.4 Additional Tuning Recommendations

You can further improve the server performance in specific scenarios by referring these recommendations.

Note the following:

  • Enable an Entry Cache. In some cases, particularly those involving relatively small directories (for example, up to a few hundred thousand entries), it can be useful to enable an entry cache. In general the FIFO entry cache provides better results than the soft reference entry cache. For more information, see "Entry Cache Configuration" in the Configuration Reference for Oracle Unified Directory.

    For large database, it is recommended that you store only a specific set of the data in the cache, by using the include-filter property.

  • Disable Unused Virtual Attributes. If the functionality needed by one or more of the virtual attributes is not required, they can be disabled for a slight performance improvement when decoding entries. For more information, see "Virtual Attribute Configuration" in the Configuration Reference for Oracle Unified Directory.

  • Disable Unused Access Logging. If access logging is not necessary, disabling the server access logger can help improve performance. For more information, see "Log Publisher Configuration" in the Configuration Reference for Oracle Unified Directory.

  • Disable Unused Access Control Handlers. If you do not need access control processing in the server, then you can disable it by setting the enabled configuration property to false for the Access Control Handler. You can set the property by using dsconfig.

  • Reduce Lock Contention. On systems with large numbers of CPUs (for example, chip multi-threading (CMT) systems with several hardware threads per core), you can reduce lock contention by setting the org.opends.server.LockManagerConcurrencyLevel system property to be equal to the number of worker threads you intend to use.

    Note:

    This property must be set as a JVM system property, because it can be required very early in the server startup process, even before accessing the server configuration.

  • Optimize Operating System Connection Closure. On a busy LDAP server, if client applications open and close connections at a high rate, the UNIX kernel can run out of connection ports, and client applications will not be able to connect to the Configuration Reference for Oracle Unified Directory server. Under these conditions, setting the following property allows the operating system to recycle the connection ports more quickly:

    Linux

    sysctl -w net.ipv4.tcp_tw_recycle=1

    Solaris

    /usr/sbin/ndd -set /dev/tcp tcp_time_wait_interval 30000

  • Optimize the Virtual Memory Swap Rate. This ensures that data stays in the filesystem cache longer. 

    sysctl -w vm.swappiness=0