Working with HCL OneTest™ API Agent logs
To configure the HCL OneTest™ API Agent logs, including those for the RunTests command when run from the command line, update the HCL OneTest™ API Agent logging properties file.
- You run tests and stubs on agents.
- You run RunTests command (from the command line) from the HCL OneTest™ API Agent installation directory.
- You experience problems and want to view the error messages.
- You see that excessive disk space is used by the HCL OneTest™ API log files.
- You want to configure the level of logging and the location of the logging files.
- You want to log metrics for the stubs that run on agents.
Configuring agent logging
- In the home installation directory of HCL OneTest™ API Agent, locate agent-logging.properties.
- Open agent-logging.properties in a text editor.
- Configure the logging handlers:You can have HCL OneTest™ API Agent write the logs to a console, to a file, or to both. Locate the property that configures the type of logging to use and update it as needed. For example:
By default, both console logging and file logging are enabled for HCL OneTest™ API Agent.agent.handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler
Agent engine processes do not have a display associated with them, and hence console logs from an engine are written into the agent log and the logging level is set to WARNING by default. Therefore, if you use console logging for the agent engines and set a different log level, there is no effect to the logs that are written.
File logging from engine processes are controlled by the
engine.java.util.logging.FileHandler.level
andengine.product_packages.level
properties found in the agent-logging.properties file.Note: You can run HCL OneTest™ API Agent from the command line or as a service. If you are running the agent as a service, you must use file logging to capture the log messages.The log files for agent and engine processes are written to the logs directory that is located at the home installation directory of HCL OneTest™ API Agent. On Windows computers, all users have modify permissions to the logs directory by default. You can modify the directory permissions to restrict the access as required after the installation.Note: The naming convention of the log files has changed over the releases. Starting from version 9.2.0, they are named as agent*.log and engine*.log. - Set the log level:Use the following properties in agent-logging.properties define the log level for the agent and engines:
agent.java.util.logging.ConsoleHandler.level
: The level at which the agent process logs to the console window, if started from the command line.agent.java.util.logging.FileHandler.level
: The level at which the agent process logs to a log file.engine.java.util.logging.FileHandler.level
: The level at which the engine process started by the agent is logged to a log file.agent.product.packages.level
: The level at which classes related to the agent are logged.engine.product.packages.level
: The level at which classes related to an engine are logged.
Set the properties to any of the following built-in log levels: SEVERE (to show the least amount of details on worst error conditions only), WARNING, INFO, CONFIG, FINE, FINER, FINEST (to display every message with more detail, most of which are not errors).Warning: Log levels associated with lower severity such as FINER and FINEST output large amounts of data to the logs, which might make your debugging process difficult. Therefore, do not use them unless necessary.
The Agent engine processes, started by the Agent process, are configured to provide file logging. The file logging for Agent Engine processes include the FINEST level of details. The Agent engine product packages export messages to the logging components with the FINEST level of details.
#------------------------------- TYPE OF LOGGING ------------------------------
agent.handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler
engine.handlers = java.util.logging.FileHandler
#---------------------------- DEFAULT LOGGING LEVEL ---------------------------
.level = INFO
#------------------------------- FILE LOGGING ---------------------------------
agent.java.util.logging.FileHandler.level = FINEST
engine.java.util.logging.FileHandler.level = FINEST
agent.java.util.logging.FileHandler.limit = 5000000
engine.java.util.logging.FileHandler.limit = 5000000
agent.java.util.logging.FileHandler.count = 2
agent.java.util.logging.FileHandler.pattern = %b/logs/agent-%u-%g.log
engine.java.util.logging.FileHandler.count = 2
engine.java.util.logging.FileHandler.pattern = %b/logs/engine-%u-%g.log
#---------------------------- AGENT CONSOLE LOGGING ---------------------------
agent.java.util.logging.ConsoleHandler.level = INFO
#------------------------------ PACKAGE LOG LEVELS ----------------------------
agent.product_packages.level = FINEST
engine.product_packages.level = FINEST
Configuring the RunTests logs
The HCL OneTest™ API Agent installation directory also contains a copy of the it-logging.properties file. This file is used to control logging when you use RunTests from the Agent installation directory. Ensure that the logging configuration file specified in RunTests.ini has the same changes applied to it while setting the log level for HCL OneTest™ API Agent.
- In the HCL OneTest™ API Agent installation directory, locate RunTests.ini.
- Find the property labeled -Djava.util.logging.config.file and verify its value. By default, this property points to the same file as it does in IntegrationTester.ini. Therefore, no additional changes are required.
Identifying engines from logs
engine.java.util.logging.FileHandler.pattern
property. Within the engine log file, INFO level messages are output with identity information:
INFO: instanceName: instance1
INFO: agentId: fb2348d5-6dec-40db-9046-44827513a44a
The instance name and agent ID can be matched to the name and ID that are shown in HCL Quality Server under the details for the Virtualization agent. To check to which stub and project this instance number applies, go to the Agents page and click for the Virtualization agent:
Increasing the logging from an engine
- Stop any stubs. When all stubs are stopped, engine processes automatically terminate after a period of inactivity (default 2 minutes). For more information about stopping stubs, see Stopping stubs.
- In
agent-logging.properties
, update theengine.product_packages.level
property as needed. For example:engine.product_packages.level = FINEST
- Save the changes.
- Restart the stubs. For more information about restarting stubs, see Starting stubs.
Setting the log file location and patterns
Locate the properties that define the log file patterns for the agent process and any engine processes and update them as needed.
- Stop any stubs. When all stubs are stopped, engine processes automatically terminate after a period of inactivity (default 2 minutes). For more information about stopping stubs, see Stopping stubs.
- Stop the agent.
- Open
agent-logging.properties
. - Update the following properties as needed:
For information about what each substitution variable (for example,agent.java.util.logging.FileHandler.pattern = %b/logs/agent-%u-%g.log engine.java.util.logging.FileHandler.pattern = %b/logs/engine-%u-%g.log
%b
) represents, see the comments in agent-logging.properties.Note: You can use forward slash (/) as the file separator character in the pattern, even on Windows systems. - Save the changes.
- Restart the agent. If you are running the agent from a command window, you can see a message that indicates to which directory the log file is being written.
- Restart the stubs.
Changing the name and location of the logging properties file
- In the home installation directory of HCL OneTest™ API Agent, locate the Agent.ini file.
- Open Agent.ini in a text editor.
- Locate the property that defines the logging properties file (
-Djava.util.logging.config.file
) and update the value as required. For example:-Djava.util.logging.config.file=./C:/myfolder/logs/itAgentLog.properties
Logging of stub metrics
When you want to obtain the performance metrics of stubs that run on agents, you can configure the agent-logging.properties file.
- Open agent-logging.properties in a text editor.
- Add the following line:
com.ghc.ghTester.runtime.actions.StubStarterAction.level = FINE
- Ensure that the following file handler is set as follows, if not add the file handler:
engine.java.util.logging.FileHandler.level = FINEST
As a result of this configuration, the stub metrics are recorded in the engine log after each event is handled.
FINE: addNumbers/addition/additionStub: Instance 1: Execution Complete. Timings: Queue To Run=0, Run to Execute=3, Execution=138, Finalization=0, Total=143
Where... | Is... |
---|---|
FINE |
Is the level of the log set for the stub metrics. |
addNumbers/addition/additionStub |
The name of the stub that ran. |
Instance 1 |
The worker that processed the request. |
Queue To Run (milliseconds) |
The time between when a message is received and the message is passed to a worker thread for processing. This time increases if the agent or stub is overloaded and might be a sign that you need more agent worker threads or to scale out to a higher number of agents. |
Run to Execute (milliseconds) |
The time between the worker thread picking up the request and starting to process the request. |
Execution (milliseconds) |
The time that is spent on processing the actions that are in the stub. |
Finalization (milliseconds) |
The time that is used to clean up and put the worker thread back into an available pool. |
Total (milliseconds) | The total time from when a request is received to the time when the worker it spawned, completes processing the request. |