Question & Answer
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
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:
- 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
- Make a back-up copy of Agent.properties.
- 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
- 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.
- 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:
- 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.
- Make a back-up copy of logging.properties.
- 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 fileC:\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
Was this topic helpful?
Document Information
Modified date:
29 September 2018
UID
swg21646751