Log

3.3.1 Log

DESCRIPTION

Log - Log a message to the script execution log file. For details see the Execution Log help topic.

Release 4.4.2 delivered execution history logging. It logs steps performed by the script in details and saves screenshots to document the progress of I/O operations. It is useful for tracking of script failures. To avoid the production of large amounts of data the logger stores just a configurable number of the most recent logs and prints them to the execution log (log.html) after the script execution finishes. For instant dump of the history logs, use the history parameter, for example when your script detects a recoverable failure.

Release 4.4.3 enhanced the history log with the option to print out the history logs to the console/terminal. The messages are printed out on the fly as they are generated without any limits. This is useful for integration with 3rd party frameworks which observe the output. 

The history logging and console output are off by default. To enable them to navigate to the Log command preferences. The console output may be also controlled from a script by setting of the _LOG_HISTORY_TO_TERMINAL variable to true as follows:

Var _LOG_HISTORY_TO_TERMINAL=true

The variable overrides the console output preference setting. It works only when the main history logging flag in preferences is enabled.

SYNOPSIS

log "<text>" [level=<logLevel>]  [terminal=<true|false>]  [history=<true|false>]
* Red colour indicates obligatory parameters

OPTIONS

text

- The log text. As the execution log file is generated in the HTML format it may contain HTML markup.

level=<logLevel>

- Optional log level, one of "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER" and "FINEST". The default value is "INFO" or the custom value specified in the Log command preferences.

Levels allow filtering the log file by the message priority. The default filter level (also called "minimum level") is "INFO" which means that the log will record only messages of this or higher level. This allows building scripts with detailed logging with an option to set off part of the logs later on through a simple change of one of the corresponding preference.

terminal=<true|false>

- The value of true will make the command copy the message to the terminal (command prompt). The default value is 'false'. Supported since v4.1.3. 

history=<true|false>

- The value of true will make the command record the most recent script history into the log file. This includes the most recent detailed logs and debug screenshots. Use it to track what had happened before the script produced an error. If the script history recording feature is disabled in the Log command preferences the parameter is ignored. The default value is 'false'. Supported since v4.4.2.

RETURNS

The command always returns 0 (zero).

EXAMPLES

Log "Suspicious image search coordinates: _SEARCH_X={_SEARCH_X}, _SEARCH_Y={_SEARCH_Y}" level="WARNING"

- Create a warning log.