If the script author has eliminated system-level failures as a problem source, the next step is to instrument scripts with log statements. Such statements can include the contents of a variable at runtime, an indication that control flow has followed a particular branch, or the results of an external service request. Before using the log statement, the script author should specify where log output will be directed.
A script author can specify a log file using the setLog() method as follows:
@script::setLog(<log file name>)
This sets the name of the log file used for output by calls to the log() method for that script.
@script::log(<log message>)
If the log file should be shared across scripts, the log file name can be set in the main script object and reused in other setLog() calls.
If a log file is not specified prior to a log statement, a randomly generated filename is used. Because this may generate a large number of small log files, it is strongly recommended that setLog() is used.
Often a script author will want to avoid generating logging for every event, and instead limit logging to events injected for test purposes. To do so, define a “debug” predicate at the event level to toggle logging on and off. When using this strategy, log statements are surrounded by conditional blocks as follows:
IF(EXISTS($event.debug))
@script::log(<log message>)
ENDIF
When the script author injects a test event, the test event includes the debug predicate to activate the debugging code.