Configuring the Cache Manager and Net.Data Caches

The Cache Manager manages one or more caches in your system. Each of these caches contains the contents of dynamically generated HTML pages. To configure the Cache Manager and each of the caches, you update the keyword values in the Cache Manager configuration file, cachemgr.cnf.

The Cache Manager configuration file contains two types of stanzas: the Cache Manager stanza and the Cache Definition stanza. The following steps describe how to customize these two types of stanzas for your application.

Defining the Cache Manager

Define the Cache Manager stanza by specifying values for the allowed keywords. All of the keywords are optional; you do not need to specify them unless you don't want to accept the default value.

To define the Cache Manager:

  1. Specify the name of the Cache Manager log file. The log shows activity for all transactions for all caches and is provided for debugging and problem analysis.

    The default is to write messages to the console.

    Syntax:

    log=path
    

    Where path is the path and file name of the cache file.

    Tip: To specify a log file for each cache, use the tran-log keyword in the Cache Definition stanza.

  2. Specify the TCP/IP port number used by the Cache Manager for incoming requests. This port number is used only for contacting the Cache Manager from a remote machine.

    This value must match the port number specified by the DTW_CACHE_PORT configuration variable in the Net.Data initialization file. The default value is determined in the following manner:

    1. The Cache Manager checks the path /etc/services for the value associated with the name ibm-cachemgrd. If this value is found, the Cache Manager uses the value. If it is not found, it uses the next method.
    2. The Cache Manager uses the default port, 7175.

    Syntax:

    port=port_number
    

    Where port_number is a unique TCP/IP port number.

  3. Specify the maximum length of time in seconds that the Cache Manager should allow a pending read to be left active. If this time is exceeded, the Cache Manager drops the connection.

    The default is 30 seconds.

    Syntax:

    connection-timeout=seconds
    

    Where seconds is the number of seconds used for the length of time a pending read should be active.

  4. Specify whether to log messages.

    The default is no or off.

    Syntax:

    logging=yes|on|no|off
    

    Where:

    yes|on
    Indicates that logging is required

    no|off
    Indicates that logging should not be performed.
  5. Specify whether to wrap the log.

    The default is no. If specified as yes, the current log is closed when it reaches its maximum size (see log-size, below), the file has a file type of .old, and a new log is opened. Only one generation of the log file is maintained (existing .old files are overwritten).

    Syntax:

    wrap-log=yes|no
    

    Where:

    yes
    Specifies to wrap the log.

    no
    Specifies not to wrap the log.
  6. Specify the maximum size, in bytes, to which a log is allowed to grow, if wrap-log is specified.

    The default is 64000.

    Syntax:

    log-size=bytes
    

    Where bytes is the number of bytes of the maximum size.

  7. Specify the level of messages to be written to the log. These values are set on when included in the trace_flag_definitions list and do not have any settings.

    The default is to log only the Cache Manager start up and shut down messages.

    Syntax:

    trace-flags=trace_flag_definitions
    

    Where:

    D_ALL
    Enables all trace flags.

    D_NONE
    Disables all trace flags

Example: Trace flag that specifies all trace flags are enabled:

trace=flags=D_ALL

Stanza example: A valid Configuration Manager stanza:

cache-manager {
port = 7175
connection-timeout = 60
logging = off
log = /local/netdata/cachemgr/logs/cachemgr.log
wrap-log = yes
log-size = 32KB
} 

Defining a Cache

Define the Cache Definition stanza by specifying values for the allowed keywords. Most keywords are optional and do not have to be specified unless you don't want to use the default value.

To define a cache:

  1. Specify the path and directory name that are to hold the cache pages. On start up, the file system containing this directory must be at least as large as the value of fssize (see below); otherwise the cache is not started. This value can be specified as an absolute path name or as a relative path name that corresponds to the path in which the Cache Manager was started.

    Required.

    Syntax:

    root=path_name
    

    Where:

    path_name
    Is the absolute or relative name of the path and directory where the cache pages are stored.
  2. Specify whether the current cache is active when the Cache Manager starts.

    Not required; the default is yes. If set to no, the cache is defined in the Cache Manager but not activated. You can activate it later with the cacheadm command.

    Syntax:

    caching=yes|no
    

    Where:

    yes
    Indicates that the cache is to be active when the Cache Manager starts.

    no
    Indicates that the cache is not to be active when the Cache Manager starts.
  3. Specify the maximum space to be used in the file system by pages in the current cache. When the maximum amount of space is exceeded, the Cache Manager deletes enough pages, starting with the oldest, to bring the total space occupied by the cache within the limit. You can effectively disable automatic purging of entries by setting this value to a large number; however, if the physical file system space is exceeded, attempts to add new pages to cache fail.

    Not required; the default is 0 (no caching to disk).

    Syntax:

    fssize=nnB|nnKB|nnM
    

    Where:

    nnB
    Is the number of bytes; for example 5000B.

    nnKB
    Is the number of kilobytes; for example 640KB.

    nnMB
    Is the number of megabytes; for example 30MB.
  4. Specify the maximum amount of memory to be used by all of the pages in this cache. When the maximum amount of memory is exceeded, the Cache Manager deletes enough pages, starting with the oldest, to bring the total memory occupied by the cache within bounds. You can effectively disable automatic purging of pages by setting this to a large number; however, if the cachemgrd process consumes too much memory, the operating system may terminate it.

    Not required; the default is 1MB.

    Syntax:

    mem-size=nnB|nnKB|nnMB
    

    Where:

    nnB
    Is the number of bytes; for example 5000B.

    nnKB
    Is the number of kilobytes; for example 640KB.

    nnMB
    Is the number of megabytes; for example 30MB.
  5. Specify the maximum length of time an page can be held in the cache. When this value is exceeded, the Cache Manager marks the page as expired but does not delete the page unless the fssize (if it is cached on disk) or memsize (if it is cached in memory) limits are reached. The Cache Manager deletes pages that are marked as expired before all other pages if memsize or fssize limits are reached. You can disable lifetime checking with the check_expiration keyword.

    Required: No; the default is 5 minutes.

    Syntax:

    lifetime=time_length
    

    Where:

    nnS
    Is the number of seconds; for example, 600S.

    nnM
    Is the number of minutes; for example, 20M.

    nnH
    Is the number of hours; for example, 30H.
  6. Specify whether to mark cache pages as expired and to perform lifetime checking.

    Not required; the default is yes, with a default lifetime length of 60 seconds. This value can also be set to a length of time, indicating a yes value and declaring a maximum length of time an item may be held in cache. When set to no, cache pages are never marked expired and lifetime checking is not performed.

    Syntax:

    check-expiration=yes|nnS|nnM|nnH|no
    

    Where:

    yes
    Indicates that the Cache Manager performs lifetime checking and cache pages are marked as expired.

    nnS
    Is the number of seconds; for example, 600S.

    nnM
    Is the number of minutes; for example, 20M.

    nnH
    Is the number of hours; for example, 30H.

    no
    Indicates that the Cache Manager does not perform lifetime checking and cache pages are not marked as expired.
  7. Specify the maximum amount of space a cached page can occupy within the memory cache. If an page is too large for memory, the file cache is checked. If adequate space exists, the Cache Manager stores the cache page in the file cache, instead. If the page does not fit in the file cache, the caching attempt fails. If the page is smaller than datum_memory_limit value (cacheobj-memory-limit), but if the cache doesn't have enough space, the oldest cache pages are deleted from the memory cache to accommodate the new page.

    Not required; the default is 1KB.

    Syntax:

    datum-memory-limit (cacheobj-memory-limit)=nnB|nnKB|nnMB
    

    Where:

    nnB
    Is the number of bytes; for example 5000B.

    nnKB
    Is the number of kilobytes; for example 640KB.

    nnMB
    Is the number of megabytes; for example 30MB.
  8. Specify the maximum amount of space a cache page can occupy within the file cache. If an page is smaller than datum_disk_limit, but no space remains in the file cache, the oldest cache pages are deleted from the file cache to accommodate the new page.

    Not required; the default is 1KB.

    Syntax:

    datum-disk-limit (cacheobj-space-limit)=nnB|nnKB|nnMB
    

    Where:

    nnB
    Is the number of bytes; for example 5000B.

    nnKB
    Is the number of kilobytes; for example 640KB.

    nnMB
    Is the number of megabytes; for example 30MB.
  9. Specify the time between creation of statistics records. If set to 0, no statistics records are written.

    Not required; the default is 0 (no statistics).

    Syntax:

    stat-interval = nnS|nnM|nnH
    

    Where:

    nnS
    Is the number of seconds; for example, 600S.

    nnM
    Is the number of minutes; for example, 1M.

    nnH
    Is the number of hours; for example, 3H.
  10. Specify the name of the path and file that are to be used for logging statistics for the current cache.

    Required when the value for stat-interval is greater than 0.

    Syntax:

    stat-files=filename
    

    Where filename is the path and name of the logging statistics file.

  11. Specify whether statistics counters should be reset to 0 each time they are written to the log file.

    Not required; the default is yes.

    Syntax:

    reset-stat-counters=yes|no
    

    Where:

    yes
    Resets the statistics counters.

    no
    Does not reset the statistics counters.
  12. Define the path and file name to hold the transaction log for each cache. Cache transaction log files are separate from Cache Manager log files, which are used to log overall Cache Manager activity.

    Required; if not specified, a transaction log for the cache is not created.

    Syntax:

    tran-log=filename
    

    Where filename is the path and file name of the transaction logs for each cache.

  13. Specify whether to turn on transaction logging for the cache when the Cache Manager first starts up. This parameter is ignored unless a valid transaction log file is specified via the tran-log parameter. You can activate transaction logging while the Cache Manager daemon is running using the cacheadm command if a valid tran-log value has been specified in the Cache Manager configuration file.

    Not required; the default is no.

    Syntax:

    tran-logging=yes|on|no|off
    

    Where:

    yes|on
    Indicates that logging is required.

    no|off
    Indicates that logging should not be performed.
  14. Specify whether the transaction log should be wrapped.

    Not required; the default is yes. If specified as yes, the current log is closed when it reaches the maximum size (see tran-log-size), has file type of .old, and a new log is opened. Only one generation of the log is maintained (existing .old files are overwritten).

    Syntax:

    wrap-tran-log=yes|no
    

    Where:

    yes
    Indicates to wrap the log.

    no
    Indicates to not wrap the log.
  15. Specify the maximum size in bytes to which a transaction log is allowed to grow, if wrap-tran-log is specified.

    Not required; the default is 64000.

    Syntax:

    tran-log-size=bytes
    

    Where bytes is the number of bytes of the maximum size.

Stanza example: A valid Cache Definition stanza for a cache:

cache0
{
root = /locale/netdata/cachemgr/caches/cache0
caching = on
mem-size = 10MB
fs-size = 1MB
datum-memory-limit = 200KB
datum-disk-limit = 1MB
lifetime = 6000000
check-expiration = 999999
tran-logging = no
tran-log-size = 10000
wrap-tran-log = yes
tran-log = /ocale/netdata/cachemgr/logs/tran.log
}
 


[ Top of Page | Previous Page | Next Page | Index ]