6.2 Configuring the ARM Agent

< Day Day Up >

The ARM engine uses a configuration file to control how it runs, the amount of system resources it uses, and so on. The name of this file is tapm_ep.cfg. This file is created on the Management Agent the first time the ARM engine is run. The location of this file is one of the following:

Windows	$MA_DIR\arm\apf\tapm_ep.cfg
UNIX	$MA_DIR/arm/apf/tapm_ep.cfg

Where $MA_DIR is the root directory where the TMTP Version 5.2 agent is installed.

The contents of this file are read when the ARM engine starts. In general, you will not have to change the values in this file, as the defaults will cover most environments. If changes are made to this file, they are not loaded until the next time the ARM engine is started.

Note

The ARM agent (tapmagent.exe) is started by the Management Agent, that is, to start and stop the ARM agent, you will need to stop and start the Tivoli Management Agent. On Windows-based platforms, this is achieved by stopping and starting the "Tivoli TransPerf Service" (jmxservice.exe). On UNIX platforms, the Management Agent is stopped and started using the stop_tmtpd.sh and start_tmtpd.sh scripts.

The contents of the file are organized in stanzas (denoted by a [ character followed by the section name and ending with a ] character). Within each section are a number of key=value pairs.

Some of the more interesting keys are described below.

The entry:

 [ENGINE::LOG]    LogLevel=1

defines the level of logging that the ARM engine will use. The valid values for this key are shown in Table 6-1 on page 185.

Table 6-1: ARM engine log levels
Value	Description
1	Minimum logging. Error conditions and some performance logging.
2	Medium logging. All of 1 and more.
3	High logging. All of 2 and much more.

The logging from the Management Agent ARM engine is, by default, sent to one of the following files:

Windows	C:\Program Files\ibm\tivoli\common\BWM\logs\tapmagent.log
UNIX	/usr/ibm/tivoli/common/BWM/logs/tapmagent.log

If you are experiencing problems with the ARM agent, you can set this key to 3 and stop and start the Management Agent to get level 3 logging.

These two keys:

 [ENGINE::INTERNALS]    IPCAppToEngSize=500    IPCEngToAppSize=500

define the size of internal buffers used for communications between ARM instrumented applications and the ARM engine. The IPCAppToEngSize key defines the number of elements used for ARM instrumented applications to communicate to the ARM engine. Likewise, the IPCEngToAppSize key defines the number of elements used for communications from the ARM engine back to the ARM instrumented applications.

In this example, 500 elements are assigned to each of these buffers. The larger these buffers are, the more memory is taken up by the ARM engine. If the application being monitored is a single threaded application, and only one application is being monitored, then these numbers can be decreased. This is not normally the case. Most applications are multithreaded and need a large number of entries here. If the number of entries is set too low, applications making many calls to the ARM engine will be blocked by the ARM engine until an unused entry is found that will slow the ARM instrumented application.

In general, changes to these two entries should only be necessary on a UNIX Management Agent and the values for the two entries should be kept the same.

If the ARM engine will not start and the log file shows errors in IPC, attempt to lower these values.

Some other interesting key value pairs include:

TransactionIDCacheSize=100000	This is the number of transactions that are allowed to be active at any specific point in time. Once this limit is reached, the least recently run transaction mapping is removed from memory and a arm_getid call must proceed any future start calls for that transaction ID mapping.
TransactionIDCacheRemoveCount=10	This is the number of transactions we flush from the cache when the above limit is reached.
PolicyCacheSize=100000	This is the number of transaction IDs to policy mappings kept in memory at any one time. This saves TMTP from having to perform regular expression matches for every policy each time it sees a transaction. Making this larger than TransactionIDCacheSize really does not have any value, but setting it equal is a good idea. This cache has to be flushed completely every time a management policy is added to the agent.
PolicyCacheRemoveCount=10	When the above cache size limit is reached, this many entries are removed.
EdgeCacheSize=100000	This is the number of unique edges TMTP has "seen" that are kept in memory to avoid sending duplicate new edge notifications to the Management Server. This cache can be lowered or raised freely depending on your memory consumption desired. Lowering it can potentially cause more network agent and Management Server load, but less memory requirements on the agent.
EdgeCacheRemoveCount=10	This is the number of edge entries to remove when the above limit is reached.
MaxAggregators=1000000	This is the maximum number of unique aggregators to keep in memory for any one hour period. It is advisable to have this set as high as possible, given your memory limit desires for the Management Agent. Warnings will be logged when this limit is reached and the old aggregator in memory will be flushed to disk.
ApplicationIDfile=applications.dat	The file name to store previously seen applications.
RawTransactionQueueSize=500	This is the maximum number of simultaneously started transactions that have not yet completed that TMTP will allow.
CompletedTransactionQueueSize=250	This is the maximum size of the completed transaction queue. These are transactions that have completed and are awaiting processing. When this limit is reached, the ARM STOP call will block while it waits for transactions to be processed and space to be freed. This can be raised at the expense of memory to allow your system to handle large rapid bursts of transactions to occur without noticeable slowdown of the response time.

Most of the other Key/Value pairs in this file are legacy and do not have any effect on the behavior of the agent.

ARM Engine log file

As described above, the Management Agent ARM engine, by default, sends all trace logs to one of the following files:

Windows	C:\Program Files\ibm\tivoli\common\BWM\logs\tapmagent.log
UNIX	/usr/ibm/tivoli/common/BWM/logs/tapmagent.log

The location of this file is determined by the file.fileName entry in one of the following files:

Windows	$MA_DIR\config\tapmagent-logging.properties
UNIX	$MA_DIR/config/tapmagent-logging.properties

To change the location of the ARM engine trace log file, simply change the file.fileName entry in this file. Please note that the logging levels specified in this file have no effect. To change logging levels for the ARM agent, you will need to modify the logging level entries in the tmtp-sc.xml file, as described in the previous section.

To get a more condensed version of the ARM engine trace log, set the fmt.className entry to ccg_basicformatter (this line exists in the tapmagent-logging.properties file and only needs to be uncommented; comment out the existing fmt.className line).

ARM data

The ARM Engine stores the data that it collects in the following directory in a binary format prior to being uploaded to the Management Server:

 $MA_HOME\arm\mar\.Dat

By default, this directory is hidden. At each the end of each upload period, this data is consolidated and placed into the $MA_HOME\arm\mar\.Dat\update directory, from where it is picked up by the Bulk Data Transfer service to be forwarded to the Management Server.

If instance records are being collected by the ARM agent another directory called $MA_HOME\arm\mar\.Dat\current will be automatically created, which will contain subdirectories for each of the instance records.

< Day Day Up >