RIT-Agent log 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.

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

-Djava.util.logging.config.file=./Agent.properties

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 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



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