Editor: Simulation Logger
Unreal Logs
The standard Unreal log panel often displays a lot of Unreal messages which are typically not useful to the average user. These messages, although will contain useful content like errors and warnings from Nominal’s simulation systems, can easily become cluttered. This makes it harder to debug systems in Unreal. The following is an example of Unreal logs, all of which are produced by the Unreal Engine and not in response to any user content.
Nominal for Unreal Logs
The new logging system filters out the logs and will save important Nominal information to a text file. Each log is stamped with both a real local timestamp and a simulation timestamp. This can make it easier to debug at what point in the simulation an error was thrown or information was printed. To enable the logger, select Project Settings (from the Edit menu in the Unreal toolbar) and navigate the left-sidebar to Nominal for Unreal Settings. The logger can be enabled by selecting the Enable Logger System.
There are several options for the logger system:
- Log Date Time: A flag indicating whether the local timestamp of the log time should be printed to the text file.
- Log Simulation Time: A flag indicating whether the current simulation time in seconds should be printed to the text file.
- Remove Old Log: A flag indicating whether only one log should be present per level, removing any older log files that exist and overwriting them.
- Non-Critical Message Frequency: A frequency in simulation time for general ‘Log, Display and Mono’ messages to be printed to the text file. This helps if there are a lot of prints which may clutter the file. Error messages will always be printed regardless of the frequency.
- Verbosity Filters: These filter out what kind of messages should be printed to the file. By default, all are turned off but can be removed based on the messages.
- Mono: These messages come from the Mono backend and will include all information from the Mono system, including creating new references and when objects are garbage collected.
- Display: Typically, the log widget used in Nominal Editor and other UI display widgets will output their status to the display category, printing the data to the file.
- Log: This is a typical print line message using the logger system and messages can be printed by the user.
- Warning: If references are misplaced or there is a warning message from the simulation back-end, this will be captured here.
- Error: An error will include any simulation component error causing a crash or if some data is used incorrectly. This will not include any Unreal errors or Blueprint compile errors.
Log files are saved in the /Saved/Logs/Nominal/ directory, under the name of the level that is being run. Each log file is particular to the level, making it easy to find the file once run.
As an example, in this particular level, there are some UI log widgets. These will output their data every time they are updated to the Display category. This can often clutter the logger. As such, a larger time step between messages or disabling the display messages can help with cleaning up these files.
Finding Errors
If an error is thrown by the Mono-backend or simulation system, the easiest way to debug this is by turning on the logger and filtering out all other categories except the Error and Mono categories. This can be done in the Nominal for Unreal Settings.
Custom Logging
Although many of these log messages are outputted automatically by the simulation, messages can be logged by the user in the level blueprints using the log system. This can be done by finding the Logger Subsystem from the Blueprint graph.
From here, several functions allow logging with different verbosities to occur. Each of the verbosities (except for the Mono category) can be printed to the log, which will be written to the file if the filter for that category is selected.
Note
If you have bugs or errors in the level and are unable to debug, Nominal Systems will often ask for the log file. Please ensure that both the Error and Mono filters are selected and send the team an appropriate log file after running the level for a significant amount of time. This will help with debugging the issue.