IBM Support

RIT-Agent log files

Technote (FAQ)


Question

How do you locate and configure logging for the IBM Rational Integration Tester Agent (RIT-Agent)?

Cause

  • You are running tests, probes and stubs on RIT-Agents.

  • You are experiencing problems and wish to view any error messages.

  • You see excessive disk space used by log files such as rit_agent_log.

  • You wish to configure the level of logging and location of the files.

Answer

INTRODUCTION

RIT-Agent takes settings from the Agent.properties file in the RIT-Agent installation folder.

When stubs are deployed and tests are scheduled, RIT-Agent starts an instance of RunTests which has its own logging configuration in logging.properties.

When performance tests are run, RIT-Agent starts an instance of TestEngine and optionally Probe.
TestEngine logging is also configured in the file logging.properties.
Probe logging is configured in the file config/Probe.config.

All of the programs use the Java logging framework. Consult the Java logging framework documentation in conjunction with this technote.

Each program has its own INI file with the same name as the executable. This determines the logging file to be used. Below is a detailed example of logging configuration for RIT-Agent.
Following this, is an example logging configuration to assist in debugging stub execution.

APPROACH

  • Increase the logging level for RIT-Agent in order to investigate issues such as failure to start or premature exit.
  • Increase the logging for the other programs such as RunTests to investigate problems during execution.

Note that the console output of these programs is automatically passed back to RIT-Agent to log or display according to its configuration.

On non-Windows systems such as Linux, a script will be used to start and stop RIT-Agent.
The script supplied with RIT contains the following lines:

logpath=/var/log/rit
...
nohup ./$executable 2>&1 >> $logpath/rit_agent_log & echo $! > $pidfile

This will result in all console output of RIT-Agent being appended to the file.
To prevent this file from growing too large, disable console output and use the file logging configurations. This method can be used with file-rotation and file-size limits.

RIT-AGENT EXAMPLE

The RIT-Agent program that runs is Agent.exe on Windows systems and Agent on non-Windows systems. The logging configuration file is defined in the Agent.ini file located in the RIT-Agent installation folder.


    For Windows systems this is typically C:\Program Files\IBM\RIT-Agent
    For non-Windows systems this is typically /opt/IBM/RIT-Agent

The value of java.util.logging.config.file defines the file to be used, and by default is Agent.properties. An example follows:

    -Djava.util.logging.config.file=./Agent.properties
Note: Any changes you make to Agent.ini will be lost when Library Manager is next run.


By default the file ibm-rita0.log is created in the home folder of the user that is running the Agent process.
When RIT-Agent is run as a Windows service this is typically in C:\Windows\System32\config\systemprofile.

Consider the following steps if you wish to change the logging configuration:

  1. Stop the RIT-Agent process or service.

    On Windows systems stop the IBM RIT Agent service.
    For non-Windows systems refer to technote Start/Stop script for RIT-Agent

  2. Make a back-up copy of Agent.properties.

  3. Edit Agent.properties and set the following:

    a) Location of the log file. The Windows path separator must be escaped using '\\'.

    java.util.logging.FileHandler.pattern = C:\\Temp\\ibm-rita%u.log

    b) Number and size of log files to be rotated

    java.util.logging.FileHandler.limit = 5000000
    java.util.logging.FileHandler.count = 10

    c) Minimum level of file logging

    .level = INFO
    com.ghc.level = INFO

    The default level of INFO is usually sufficient. It also includes the higher levels WARNING and SEVERE.
    The order from highest severity down to the lowest is:

    SEVERE
    WARNING
    INFO
    FINE
    FINER
    FINEST

    If you wish to change the logging level, change or add only these values:

    com.ghc.level=FINE
    java.util.logging.ConsoleHandler.level = FINE
    java.util.logging.FileHandler.level = FINE


  4. Ensure that the file system permissions allow the log files to be created in the chosen destination.

    a) Run RIT-Agent on the command line and verify that the log file is created.
    b) Check the console output for error messages related to logging.

  5. Re-start RIT-Agent to pickup the changes.


RUNTESTS LOGGING

RunTests console output is automatically passed to the Agent process as INFO level. These messages are then logged according to the RIT-Agent logging configuration, either to file or console or both.

Generally it does not make sense to configure RunTests to log to file and console as you will get duplicated logging of all messages. You will see the messages in the RunTests log and the Agent log.

Enable stub logging when you deploy it if you wish to see stub event activity in the logs.
By default logging is turned off when a stub is deployed to improve performance, you must enable it in the Configuration > Logging section of the Start Stub window.
This setting can be saved by creating a scenario once your stubs are running with the configuration you want.

Read through the RIT_AGENT EXAMPLE section above to understand the location and naming of files, and the way that they are edited. Follow these steps to configure detailed console logging for RunTests:

  1. Stop any stubs and verify that no RunTests processes are running.
    It is safe for RIT-Agent to be running if you are not changing Agent.properties.

  2. Make a back-up copy of logging.properties.

  3. Edit the file and set the following parameters:


    handlers= java.util.logging.ConsoleHandler

    java.util.logging.ConsoleHandler.level = FINE

    com.ghc.level = FINE
    com.ibm.rational.level = FINE


Here is an example of some of these FINE messages as they appear in the RIT-Agent console:

INFO: VirtualAppinstance1 (0): FINE: Attempting to listen on 0.0.0.0/0.0.0.0:8819
...
INFO: VirtualAppinstance1 (0): FINE: HTTP server for HTTP transport http localhost:8819 is already running, on port: 8819

Note that they are RIT-Agent INFO messages but contain the RunTests FINE text.
In the above example we can see the TCP port number being used by the stub HTTP transport.

Each message is prefixed with the instance number. To see which stub and project this applies to go to the RTCP Agents page and click for the RTVS agent:



NOTES:

  • A sample Agent.properties file is attached.
    This can be used on Windows systems to output the INFO level of logging to the file C:\Temp\ibm-rita0.log, and the console.

  • A sample logging.properties file is attached.
    This can be used to enable detailed logging for stub and test execution; the output is passed to RIT-Agent to write to its log.

  • Setting a very fine level of logging can impair the performance of the Agent.
    For example if you set the finest level of logging for RIT-Agent it will fill the log with Rational Test Control Panel (RTCP) polling messages.
    After debugging any issues reduce the logging.

  • Do not be tempted to enable fine logging for everything as this will log every Java activity making it almost impossible to find the issue you are investigating.
    Do not set this:

    .level = FINE

  • Other programs such as IBM Rational Integration Tester (RIT) use the same logging mechanism.
    Locate the executable such as GHTester.exe or RunTests.exe and then view the matching .ini file.
    Follow the steps as shown above.

  • You can turn off the file logging by changing the following entry to remove the FileHandler entry:

    handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

    handlers= java.util.logging.ConsoleHandler

Disclaimer

All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Agent.propertiesAgent.properties logging.propertieslogging.properties

Document information

More support for: Rational Test Virtualization Server
RIT Load/Stub Agent

Software version: 8.0, 8.5, 8.6, 8.7, 9.0

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 1646751

Modified date: 22 April 2016