Home

Welcome to the GoLogger wiki!

GoLogger uses 'sessions' to indicate when the plugin is logging or not. Each session creates new log files for every category you've setup with the timestamp of when the session was started. Sessions are also global, meaning that stopping a session will start and stop logging for all categories simultaneously. There are three main ways to start and stop sessions.

• Using the autostart setting which is on by default.
• Hotkeys can perform the three main functions of the plugin - start Ctrl + Shift + O, copy - Ctrl + Shift + U and stop - Ctrl + Shift + P
• Calling the functions though code. You can call the functions through code from any script or scene since the script is an autoload.

The 'Save copy' feature was introduced in v1.2 which allows users to save copies of the logs of an active session into each category's respective saved_logs subfolder. When this is initiates, a text prompt is activated for you to specify a name of the copied log. This feature serves two key purposes:

• Prevent Deletion: Log files are automatically deleted when the file limit is reached. Saving a copy protects specific logs from being removed. You can also manually move any log file(s) out of the category folder will of course also prevent deletion.
• Preserve Important Data: When using the Entry Count Limit + Overwrite Entries options to limit file size, older entries are deleted to make room for new ones. If a bug or unexpected event occurs during playtesting, you can use this feature to save the log without requiring you to stop and start the session or your game without the risk of overwriting the important log entries.

Example usage of the main functions:

Concatenating data and strings can be done though many ways, and creating strings for log entries are no different. Use your prefered method, but below are some examples of how to use the main methods of this framework.

# General use, simply starts the session. Hotkey:  Ctrl + Shift + O
Log.start_session()
# Starts session 1.2 seconds after the call. Requires the use of 'await'.
await Log.start_session(1.2)

# No category_index defined > defaults to category 0("game" category by default).
Log.entry(str("Current game time: ", time_of_day))
# Resulting entry : [19:17:27] Current game time: 16.30

# Logs into category 1("player" category by default). 3 ways to format the same string.
Log.entry("Current Player health: " + str(current_health) + "/" + str(max_health), 1)
Log.entry(str("Current Player health: ", current_health, "/", max_health), 1)
Log.entry(str("Current Player health: %s/%s" % current_health, max_health), 1)
# Resulting entry: [19:17:27] Current Player health: 74/100

# Copy session anytime the "player_death" signal is emitted. Hotkey:  Ctrl + Shift + U
func _on_player_death() -> void:
  Log.save_copy()

# Stops an active session. Hotkey:  Ctrl + Shift + P
Log.stop_session() 

The index of every category is shown in the "Categories" tab of the dock at the top left of each category.

Creating log entries with data:

Simply installing GoLogger will not log any entries or data. This plugin is a framework for you to define your own log entries in your code as you develop your project. Entries are simple strings, meaning any data that can be converted to a string by using str(data) can be added to an entry.

When creating a log entry, you only need to create a string and concatenate any data you need. The only need to be mindful of specifying the category_index which depends on the categories you use. If you for example want to log the current time in your game and the players current position in two separate entries when you've loaded your game(also assuming you have the default categories). See the Example Usage of the main functions paragraph for real world examples of how entries can be made.

Without defining a category_index when creating log entries(i.e. Log.entry("This is a log entry.")). Entries are logged into the category with the index 0.

Managing log categories:

GoLogger will create directories for each category in the dock's "category" tab. By default, a "game" and a "player" category is added for you but you can add, remove or rename them to fit your needs. The top-left number of each category is the category_index which you use whenever you create log entries in your code. When your project runs, folders are created with the name of each category within the base_directory and ones a session is started. A .log file is created for each category and is stored in the category's folder.

Notes:

• Locked categories are deleted when using the Reset button. The lock button just disables the text field, apply and delete buttons.
• Folders for categories created by the plugin aren't deleted when you delete a category in the dock. This is to prevent accidental deletion of log files. It's best to open the directory using the "Open" button and manually delete the corresponding folder of any deleted category.

Managing .log file size:

A potential pitfall to consider when logging large/growing data is how Godot's FileAccess API handles file writing. The FileAccess.WRITE mode truncates(deletes) the file's content, meaning we can't simply append new entries to a file. The plugin first reads the file and stores each entry in an array which are then re-entered sequentially before appending a new entry. This process can cause performance issues as the entry count grows, thereby creating larger arrays that are prone to performance issues.

It is therefore vital to put limitations in place, which GoLogger offers a couple of options. In the settings tab of the dock, you can find Limit Method, each method has its own Action to determine the action taken once the condition of the method is fullfilled.

Entry Count Limit(recommended):

As the name suggests, the number of entries are counted and is used together with the settings Entry Count Action and entry cap. The Entry Count Action is triggered once the entry count exceeds the set entry cap. Actions available for this method:

• Overwrite entries removes the oldest entries as new ones are written. This is the safest and objectively better option to use. However, this potentially deletes important logs. So be mindful that you should either stop the session manually, copy the session or quit your game to prevent any entry loss.
• Stop session will of course stop the session once the cap is hit. Requires you to start the session either manually or through code to log again.
• Restart session restarts a session, creating a new log file.
  

Session Timer:

A timer is started alongside sessions and the Action is triggered upon timeout. The session timer has uses outside of solving the file size issue. For example, if you don't want to log at all times, only when testing or stress testing that requires you to log during certain times. The session timer features signals that allows you to sync up the session and a test with session_timer_started and session_timer_stopped. Actions available for this method:

• Stop session will stops sessions on session timer timeout. Requires you to start the session either manually or through code to log again.
• Restart session restarts sessions, creating a new log file.

You can also use both Entry Count Limit and Session Timer simultaneously!

None(beware):

You can also choose to use none of the Limit Method options. This can be useful if you don't have sessions running in the background at all times. For example, if you use GoLogger only when you want to test a specific feature or system and you're manually stopping and starting the sessions as you need them. This is NOT RECOMMENDED unless you're aware of the problems that can occur. Use at your own risk!

File count limit:

Despite .log files taking minimal storage space, generating an endless amount of files is never a good idea. Therefore, GoLogger has an adjustable file count limit setting that limits the number of .log files allowed in the category folders. By default, this limit is set to 10 and will overwrite the log file with the oldest date- and timestamp. Moving a .log file out of the folder saves it from this overwrite action.
It's possible to turn this off by setting the value to 0 but it is NOT recommended!