Logging
XenoGuard stands out with its extensive logging interface, ensuring accurate documentation of all data generated during script execution and thus enabling thorough post-execution analysis. The logging system is divided into two main levels to comprehensively cover both automated and manual logging requirements.
On the first level, data recording is carried out by the Execution-Core, the central execution engine of XenoGuard. This records all relevant data, including the actions to be executed, their input and output parameters, and any errors that occur. This complete documentation not only facilitates retrospective traceability of the script's progress but also serves as a valuable resource for error analysis, troubleshooting, and report generation. Additionally, the recorded database is utilized by IntelliRun®, a tool that visually processes execution data and allows for detailed analysis of the results after execution. A separate section will later deal extensively with IntelliRun.
On the second level, users have the option to manually write data into the log files during script execution. With an optional additional extension, further logging channels can be created and textually populated.
All generated data is secured in a separate database for each Master Script on the hard drive. Thanks to the functionality for parallel script execution, the databases are instantiated multiple times, allowing simultaneous and independent recording of data.
Another feature of XenoGuard is the differentiated error level system, which distinguishes between various severity levels such as Information, Warning, and Error. The configuration settings also offer users the option to choose between two detail levels: either comprehensive logging of all action data or recording of critical error events only. The former option requires more storage space and sufficient system resources for timely data storage.
|
Each logging entry in XenoGuard is referred to as an entity and receives a unique, high-precision system timestamp, generated during logging and stored along with the other data. This also applies to individual text entries. |
The following sections will provide a detailed presentation of XenoGuard's logging system.
Turning Automated Logging On and Off
Automated logging in XenoGuard allows for comprehensive capture and archiving of all relevant data and events during the execution of a script. When you activate logging and start a script, XenoGuard automatically collects all necessary information, including the actions performed, input and output parameters, execution duration, errors encountered, and processed child scripts.
To activate logging, navigate to the Ribbon menu and look for the Logging group. With the Logging toggle button, you can turn automatic logging on or off:
Database Storage Location
XenoGuard creates a separate logging directory for each Master Script. The name of this directory begins with the current timestamp in the format "yyyy_MM_dd__HH_mm_ss_fff <Filename>."
Here are the individual components of the format:
- yyyy: Four digits for the year
- MM: Two digits for the month
- dd: Two digits for the day
- HH: Two digits for the hour in 24-hour format
- mm: Two digits for the minute
- ss: Two digits for the second
- fff: Three digits for the millisecond
- <Filename>: A placeholder for the individual file name
For example, if you run the script "Example" on October 23, 2023, at 15:45:30.123, the folder name will be "2023_10_23__15_45_30_123 Example."
|
|
By default, XenoGuard creates the logging directory in the Protocols subfolder of the Workspace. |
Status Display
Data recording begins immediately with the start of the Master Script. After each executed action, XenoGuard collects the data and forwards it to the logging interface, which stores it in the database. You can view the progress of data recording in XenoGuard's status bar. In the lower right corner, the number of logged actions, the number of stored entities, and the number of buffered entities are displayed. The latter can grow rapidly, depending on the script, and therefore requires sufficient memory for buffering.
|
|
The speed at which data is stored can lag behind the script execution, depending on the script structure, the number of loops, processed data, and performed operations. This causes the buffered data area to grow steadily. The buffer area continues to be processed even after the script is completed, as data are continuously stored in the database in the background. You can follow the progress of this process in the Executions window, which will be introduced later. |
Terminating Data Recording
If you wish to terminate data recording prematurely, for instance, due to a detected error in the script, you can use the Cancel Logging option (see Ribbon menu). This immediately interrupts the logging output. Please note that the recorded data will be incomplete in this case.
Logging Detail Level
In XenoGuard, there are two different logging levels that allow you to adjust the type and extent of the data recorded:
-
All ActionSteps: This logging level enables comprehensive recording of all actions that take place during script execution. Every step of the script, including the actions performed, their input and output parameters, and the duration of execution, is documented in the log files. This detailed recording provides an accurate insight into the script execution process and is particularly helpful for error analysis and script optimization.
- All Errors: This logging level focuses on capturing errors that may occur during script execution. Instead of recording every detail of the script's progress, only relevant error information is captured. This includes error messages, the affected actions and their parameters, and possibly additional context information that can contribute to error resolution. This logging level is less memory-intensive and is well-suited for scripts where complete logging is not necessary and the focus is on identifying and resolving errors.
To make Workspace settings in XenoGuard, open the settings dialog box by clicking on Settings in the Ribbon menu. Then switch to the Execution Configurations tab. Here, in the General section, you will find the desired setting options:
Manual Text Entries
When logging is active, you can use the Write Text action to save text messages in the logging data. XenoGuard inserts the entered text strings into a specially created text file named ActionStepOutput.txt, along with a system timestamp. This action also allows you to set the log status, differentiating between Unqualified, Passed, and Failed states:
- Unqualified: This status marks a neutral text entry and does not affect the error statistics.
- Passed: This status is assigned when the text entry marks a faultless process, positively contributing to the error statistics.
- Failed: This state indicates a faulty process that is recorded as an error in the statistics.
If logging is disabled, the Write Text action remains usable. However, the outputs are not stored in the database but are only visible in the result list of the action.
HTML Logs
In addition to these extensive logging functions, XenoGuard offers the option to export an HTML log. This allows users to present and share the logged information in an easily readable and accessible format. The HTML format is excellent for displaying the logs in reports and for archiving, as it can be directly viewed in web browsers and facilitates user-friendly navigation through the log data. Read here, to get more information.