CACHEMGR

Valid For

Extract and Replicat, all databases except DB2 on z/OS

Description

Use the CACHEMGR parameter to control the amount of virtual memory and temporary disk space that is available for caching uncommitted transaction data.

Caution:

Before changing this parameter from its default cache settings, contact Oracle Support for guidance. The cache manager of Oracle GoldenGate is internally self-configuring and self-adjusting, and most production environments will not require changes to this parameter. You can, however, specify the directory for the page files without assistance.

About Memory Management

Note:

While described as accurately as possible here, the underlying design of the memory management component is always subject to changes that may be required by ongoing product improvements.

Because Oracle GoldenGate replicates only committed transactions, it stores the operations of each transaction in a managed virtual-memory pool known as a cache until it receives either a commit or a rollback for that transaction. One global cache operates as a shared resource of an Extract or Replicat process. The following sub-pools of virtual memory are allocated from the global cache:

  • One sub-pool per Extract log reader thread or Replicat trail reader thread for most transaction row data.

  • One sub-pool for BLOB data and possibly other large items.

Within each sub-pool, individual buffers are allocated from the global cache. Each buffer contains information that is relative to a transaction that is being processed by Oracle GoldenGate.

The Oracle GoldenGate cache manager takes advantage of the memory management functions of the operating system to ensure that Oracle GoldenGate processes work in a sustained and efficient manner. Within its cache, it makes use of modern virtual memory techniques by:

  • Allocating and managing active buffers efficiently.

  • Recycling old buffers instead of paging to disk, when possible.

  • Paging less-used information to disk, when necessary.

The actual amount of physical memory that is used by any Oracle GoldenGate process is controlled by the operating system, not the Oracle GoldenGate program.

The cache manager keeps an Oracle GoldenGate process working within the soft limit of its global cache size, only allocating virtual memory on demand. (The cache manager does not allocate physical memory, over which it has no control.) System calls to increase the cache size are made only as a last resort and, when used, are always followed by the release of virtual memory back to the system.

The system must have sufficient swap space for each Oracle GoldenGate Extract and Replicat process that will be running. To determine the required swap space:

  1. Start one Extract process and one Replicat process.

  2. Run GGSCI.

  3. View the report file of each running process and find the line PROCESS VM AVAIL FROM OS (min).

  4. Round up each value to the next full gigabyte if needed. For example, round up 1.76GB to 2 GB.

  5. Multiply the rounded-up Extract value by the number of Extract processes.

  6. Multiply the rounded-up Replicat value by the number of Replicat processes.

  7. Add the two results, plus any additional swap space required by other Oracle GoldenGate processes and other processes on the system.

    (PROCESS_VM x number_Extracts) + (PROCESS_VM x number_Replicats) +
    (swap_for_other_processes) = max_swap_space_on_system
    

    This sum is the maximum amount of swap space that could be needed for those processes. The actual amount of physical memory that is used by any Oracle GoldenGate process is controlled by the operating system, not the Oracle GoldenGate process. The global cache size is controlled by the CACHESIZE option of CACHEMGR.

Note:

The cache manager is also used internally by Oracle GoldenGate for other purposes besides the BLOB sub-pool and the sub-pool for other transaction data. You may see these additional memory pools when you view the statistics.

When to Adjust CACHEMGR

The memory manager generates statistics that can be viewed with the SEND EXTRACT or SEND REPLICAT command when used with the CACHEMANAGER option. The statistics show the size of the memory pool, the paging frequency, the size of the transactions, and other information that creates a system profile.

Based on this profile, you might need to make adjustments to the memory cache if you see performance problems that appear to be related to file caching. The first step is to modify the CACHESIZE parameter. You might need to use a higher or lower cache size based on the size and type of transactions that are being generated.

It is possible, however, that operating system constraints could limit the effect of modifying any components of the CACHEMGR parameter. In particular, if the operating system has a small per-process virtual memory limit, it will force more file caching, regardless of the CACHEMGR configuration.

See "SEND EXTRACT" and "SEND REPLICAT" for more information.

Viewing Basic Statistics in the Report File

Upon completing its initialization, the cache manager writes the following statistics to the process report file:

CACHEMGR virtual memory values (may have been adjusted)
CACHESIZE: 32G
CACHEPAGEOUTSIZE (normal): 8M 
PROCESS VM AVAIL FROM OS (min): 63.97G
CACHESIZEMAX (strict force to disk): 48G

Where:

  • CACHESIZE shows the soft limit of virtual memory that is available to the process for caching transaction data. It is determined dynamically, based on the value of PROCESS VM AVAIL FROM OS (min). It can be controlled with the CACHESIZE option of CACHEMGR.

  • PROCESS VM AVAIL FROM OS (min) shows the approximate amount of virtual memory that the process has determined it can use. For internal reasons, this amount may be less than what the operating system shows as being available.

  • CACHESIZEMAX (strict force to disk) is derived from PROCESS VM AVAIL FROM OS and CACHESIZE. It can be understood in terms of how the cache manager determines which transactions are eligible to be paged out to disk. Normally, only those whose current virtual memory buffers exceed a specific internal value are eligible to be paged. When the total memory requested exceeds CACHESIZE, the cache manager looks for transactions to write to disk and chooses them from the list of eligible ones. If the eligible ones have been paged to disk already, and the virtual memory in use now exceeds CACHESIZEMAX (strict force to disk), then any transaction that requires additional buffers can be eligible for paging. This guarantees that virtual memory will always be available.

Identifying the Paging Directory

By default, Oracle GoldenGate maintains data that it swaps to disk in the dirtmp sub-directory of the Oracle GoldenGate installation directory. The cache manager assumes that all of the free space on the file system is available. This directory can fill up quickly if there is a large transaction volume with large transaction sizes. To prevent I/O contention and possible disk-related Extract failures, dedicate a disk to this directory. You can assign a name and size to this directory with the CACHEDIRECTORY option of the CACHEMGR parameter. The CACHESIZE option of CACHEMGR sets a soft limit for the amount of virtual memory (cache size) that is available for caching transaction data.

Guidelines for Using CACHEMGR

  • This parameter is valid for all databases supported by Oracle GoldenGate.

  • At least one argument must be supplied. CACHEMGR by itself is invalid.

  • Parameter options can be listed in any order.

  • Only one CACHEMGR parameter is permitted in a parameter file.

  • To use this parameter correctly (other than specifying the directory for the page files), you must know the profile of the system and the kinds of transactions that are being propagated from your applications. In normal environments, you should not need to change this parameter, because the cache manager is self-adjusting. If you feel that an adjustment is warranted, please open an Oracle service request at http://support.oracle.com.

Default

None

Syntax

CACHEMGR {
  [, CACHESIZE size]
  [, CACHEDIRECTORY path [size] [, ...]]
CACHEMGR CACHEFSOPTION { MS_SYNC | MS_ASYNC } |
}
CACHESIZE size

Sets a soft limit for the amount of virtual memory (cache size) that is available for caching transaction data. On 64-bit systems, the default is 64 GB. On 32-bit systems, the cache size is determined dynamically by the cache manager.

The memory is allocated on demand. By default, the cache manager dynamically determines the amount of virtual memory that is available to it from the operating system and determines the appropriate cache size. The available virtual memory is reported with the PROCESS VM AVAIL FROM OS value in the report file. The CACHESIZE value will be sized down if it is larger than, or sufficiently close to, the amount of virtual memory that is available to the process. However, for systems with large address spaces, the cache manager does no further determination once an internal limit is reached.

The CACHESIZE value will always be a power of two, rounded down from the value of PROCESS VM AVAIL FROM OS, unless the latter is itself a power of two, in which case it is halved. After the specified size is consumed by data, the memory manager will try to free up memory by paging data to disk or by reusing aged buffers, before requesting more memory from the system.

If a transaction's cache virtual memory requirements grow beyond the initial buffer allocation, the additional amount of cache memory that is allocated by the cache manager is determined dynamically based on factors such as the current size of the cached data of this transaction, the size needed for the new data, and the amount of virtual memory that is being used conjointly by all the transactions.

CACHEDIRECTORY path [size]

Specifies the name of the directory to which Oracle GoldenGate writes transaction data to disk temporarily when necessary. The default without this parameter is the dirtmp sub-directory of the Oracle GoldenGate installation directory. Any directory for temporary files can be on an Oracle Database File System, but cannot be on a direct I/O or concurrent I/O mounted file system that does not support the mmap() system call, such as AIX.

  • path is a fully qualified directory name.

  • size sets a maximum amount of disk space that can be allocated to the specified directory. The upper limit is that which is imposed by the file system, such as maximum file size or number of files. The minimum size is 2 GB, which is enforced. There is no default. Do not use this option unless you must constrain the swap space that is used by Oracle GoldenGate because of resource limitations.

You can specify more than one directory by using a CACHEDIRECTORY clause for each one. The maximum number of directories is 100.

The value can be specified in bytes or in terms of gigabytes, megabytes, or kilobytes in any of the following forms:

GB | MB | KB | G | M | K | gb | mb | kb | g | m | k

CACHEMGR CACHEFSOPTION {MS_SYNC | MS_ASYNC}

Performs synchronous or asynchronous writes of the mapped data in the Oracle GoldenGate memory cache manager.

Example

CACHEMGR CACHESIZE 500MB, CACHEDIRECTORY /ggs/temp 2GB, CACHEDIRECTORY /ggs2/temp 2GB