Debug.Log Extensions
Documentation (1.1.9)
Debug.Log Extensions

What Is a Debug.Log Extensions?

Debug.Log Extensions enhances the debugging experience in Unity with numerous improvements.

These enhancements can greatly improve readability in the Console as well as save a lot of time by enabling you to write very compact yet highly informative debugging code.

Using Debug.Log Extensions can even help improve performance by providing you with flexible tools to help ensure all unnecessary debugging code is completely stripped from release builds.

Installation

When you first install Debug.Log Extensions to a project you will be asked whether or not you would like to have it replace the default Debug class across the project.

If you choose Yes and some classes in your project contain the statement using Debug = UnityEngine.Debug; it can prevent the project from compiling. To fix this you need to remove the statements from your code - they should no longer be necessary with Debug.Log Extensions installed. If any DLLs or packages in the project you are using contain this statement then you will not be able to replace the default Debug class and should pick 'No'.

If you choose not to replace the default Debug class you will need to add the line using Debug = Sisus.Debugging.Debug; in any classes where you want to enable Debug.Log Extensions' enhancements.

Quick Start Guide

If you installed the Debug class in the global namespace then all existing calls to methods in the Debug class will automatically be enhanced. If not, add using Debug = Sisus.Debugging.Debug; in any classes where you want to enable Debug.Log Extensions' enhancements.

See the scripting reference for the Debug class for a list of additional methods you can use during debugging.

You can open an enhanced Console window using the menu item Window > Debugging > Console+ or use the keyboard shortcut Ctrl + Shift + C.

While in Play Mode press the Insert key to switch between different view options for the in-game Debugging GUI.

  1. In Dynamic mode the GUI remains hidden unless something Debug.DisplayOnScreen has been used to add something to it.
  2. In Always On mode the GUI remains visible even if it has nothing to show.
  3. In 'Channels' mode the GUI lists all Channels that have been used in logging and allows you to enable and disable them at will.
  4. In 'Always Hidden' mode the GUI is hidden even if elements have been added to it.

To enable the in-game GUI in builds either enable the Development Build flag in Build Settings or add -log-gui-enable as a launch parameter for your application.

Features

Clean Console

By default an empty line will be automatically added at the end of all your logged messages. This has the effect of pushing the stack trace off the main list in the Console, resulting in a cleaner look.

You can customize this behaviour in Preferences > Console using the preference item Formatting > List Display Style.

Syntax Highlighting

By default all your logged messages will be enhanced with colorful syntax highlighting.

You can customize this behaviour in Preferences > Console under the group Colors.

Automatic Context

The context Object is automatically determined for your messages whenever possible to enable locating message sources by clicking log entries in the Console.

Channels

If you prefix a log message with a tag inside square brackets you can now tie it to a specific channel. Fox example:

Debug.Log("[Audio]Playing ", ()=>audioClip);

You can define new channels in Project Settings > Console by adding them to the Channels list. Here you can also customize their color in the Console view as well as whether or not the channel is enabled by default for all users.

You can also enable or disable specific channels for yourself only in Preferences > Console by adding them to the Whitelisted Channels or Blacklisted Channels lists. These whitelists and blacklists take precedence over channel configuration in the project setting.

You can turn messages logged on certain channels on and off using the dropdown menu in in the Console+ window.

In builds you can use the Channel mode in the in-game Debugging GUI to turn channels on and off.

To enable channels programmatically you can use Debug.EnableChannel and disable them using Debug.DisableChannel. These can be used both at runtime and in edit mode. Note that changes made using these commands aren't serialized, but are reset every time that scripts are reloaded in the editor or you close your application.

Console+

An enhanced version of Console window called Console+ is included with Debug.Log Extensions.

It contains a dropdown menu for easily selecting on which channels logging is currently enabled.

Stack trace for the selected message is no longer displayed as unformatted raw text but organized into various columns for easier readability. You can easily customize which columns are shown for you by right-clicking the header of any column. The new Find Objects Of Type columns lets you find all instances of any classes referenced in your stack traces with a single click.

To open the window use the menu item Window > Debugging > Console+ or use the keyboard shortcut Ctrl + Shift + C.

Personal Channel

Each user has a personal channel derived from their username. This channel is automatically enabled only in the computer of the user in question.

This means that if you log messages using your personal channel others users of the project won't see them by default.

You can use the UniqueChannel property in the Dev class to learn what your personal channel is. This is also usually the first channel listed in the Channels dropdown in the Console+ view.

If your unique channel was for example JohnDoe then you could log a message that only visible to yourself by default like this:

Debug.Log([JohnDoe]Test);`

Debug.Log(()=>field)

This new command can be used to log both the name and value of a field or a property to the console.

This can handle null values as well collections without issues.

If you use this to log a field or a property belonging to an Object, then the context for the logged message will automatically be set to said Object.

Debug.LogState(target)

This command prints the full state of a target to the console. By default this will list all public instance fields and properties. You can customize this by using the variant that contains parameters includePrivate and includeStatic.

Debug.LogChanges(()=>field)

This command can be used to print a message everytime that the value of the given field or property changes.

Note: the message will not be printed at the exact moment that the value changes, but at the end of the current frame - similar to how Debug.Break works.

Debug.LogIf(condition, message)

This command logs a message to the console only if a condition is true.

Debug.DisplayOnScreen(()=>field)

This command can be used to display the current value of a field on-screen. The value will be displayed both in the Scene view as well as the Game view via the in-game GUI.

Note: this will only work in the editor, in development builds or in non-development builds when using the launch parameter -log-gui-enable.

Debug.Ensure(condition)

The Ensure methods combine condition checks with error logging upon failure.

They also make sure an error is only logged once per session to avoid flooding the log file.

Debug.Guard(condition)

Guard methods function just like the Ensure methods but their return value is reversed, making them fitting for situations where you want to return early upon failure.

Debug.LogToFile(message)

This can be used to log messages into custom text files instead of the console and the default log file.

By default the file will be created in the same directory as your default log but using the name LogToFile.log. You can specify a different name or change the path completely using the second path parameter.

By default your log files will be cleared with each new session when you call Debug.LogToFile for the first time. You can customize this behaviour by changing the third clearFile parameter. You can also use ClearLogFile to manually clear an existing log file.

Dev class

In addition to the extensions in the Debug class a new class called Dev is also introduced.

The Dev class contains many of the same methods as the Debug class such as Log, LogWarning, LogError, LogState, LogChanges, DisplayOnScreen and StartStopwatch.

These work identically to the methods found in the Debug class but any calls to them are completely omitted in release builds. This includes any string concatenation or method calls you do in the parameters too.

Note: to reference the Dev class in your scripts you need to include the line using Dev = Sisus.Debugging.Dev; in your script.

Critical class

A new class called Critical is also introduced.

The Critical class contains many of the same methods as the Debug class such as Log, LogWarning, LogError, and Assert.

These function very similarly to the methods found in the Debug class but with three key differences:

  1. The messages use a larger font in the console window.
  2. They always include full stack trace even if stack traces have been disabled for other messages in Player Settings.
  3. The messages are always recorded in builds even if Use Player Log is disabled in Player Settings.

Note: to reference the Critical class in your scripts you need to include the line using Critical = Sisus.Debugging.Critical; in your script.