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.

Following are a few scenarios in which you need to configure logging for the HCL OneTest™ API Agent:
  • You run tests and stubs on agents.
  • You run the 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.
You can find the following information:

Configuring agent logging

To configure logging for HCL OneTest™ API Agent, do the following steps:
  1. In the home installation directory of HCL OneTest™ API Agent, locate agent-logging.properties.
  2. Open agent-logging.properties in a text editor.
  3. Configure the logging handlers by locating the property that configures the type of logging to use and update it as required.
    You can let HCL OneTest™ API Agent write the logs to a console, to a file, or to both. For example:
    agent.handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler
    By default, both console logging and file logging are enabled for HCL OneTest™ API Agent.

    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 and engine.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.

    The naming convention of the log files is as follows:
    • For the agent, the name format is agent-<unique_number>-<number_of_rotated_log>.log
    • For the engine, the name format is engine-<instance_name>-<unique_number>-<number_of_rotated_log>.log
  4. 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.
Example: In this example, the Agent process is configured to provide both console and file logging. The Agent process console messages include SEVERE, WARNING, and INFO level messages, while the Agent process file logging messages include the FINEST level of details. The Agent product packages are configured to export messages to the logging components with the FINEST level of details.

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-%i-%u-%g.log
#---------------------------- AGENT CONSOLE LOGGING ---------------------------
agent.java.util.logging.ConsoleHandler.level = FINEST
#------------------------------ PACKAGE LOG LEVELS ----------------------------
agent.product_packages.level = INFO
engine.product_packages.level = INFO

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.

  1. In the HCL OneTest™ API Agent installation directory, locate RunTests.ini.
  2. 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

All engine processes started by an agent share a common log file name pattern as defined by the 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 search for the Virtualization agent:

agent_deployed

Increasing the logging from an engine

When you deploy a stub to an agent, the running of the stub occurs in an engine process that is started by the agent. Therefore, to help diagnose problems when the stub runs, you might want to increase the level of logging for the engine processes. To change the logging level for the engine to FINEST:
  1. 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.
  2. In agent-logging.properties, update the engine.product_packages.level property as needed. For example: engine.product_packages.level = FINEST
  3. Save the changes.
  4. 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.

To change the default location, do the following steps:
  1. 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.
  2. Stop the agent.
  3. Open agent-logging.properties.
  4. Update the following properties as needed:
    
agent.java.util.logging.FileHandler.pattern = %b/logs/agent-%u-%g.log
engine.java.util.logging.FileHandler.pattern = %b/logs/engine-%i-%u-%g.log
    For information about what each substitution variable (for example, %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.
  5. Save the changes.
  6. 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.
  7. Restart the stubs.

Changing the name and location of the logging properties file

Change the name and location of the logging properties files as follows:
  1. In the home installation directory of HCL OneTest™ API Agent, locate the Agent.ini file.
  2. Open Agent.ini in a text editor.
  3. 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.

Perform the following steps:
  1. Open agent-logging.properties in a text editor.
  2. Add the following line:
    com.ghc.ghTester.runtime.actions.StubStarterAction.level = FINE
  3. Ensure that the following file handler is set as follows, if not add the file handler:
    engine.java.util.logging.FileHandler.level = FINEST
Note: It is not necessary to restart the agent for this configuration to come into effect, but the change in configuration does not affect engines that are already running stubs.

As a result of this configuration, the stub metrics are recorded in the engine log after each event is handled.

After you configure for logging of the stub metrics, you can view the log for each event as follows:
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.