Debug error log unity

using UnityEngine;
using System.Collections;
public class MyGameClass : MonoBehaviour
{
    private Transform transform;
    void MyGameMethod()
    {
        if (transform == null)
            Debug.LogError("memberVariable must be set to point to a Transform.", transform);
    }
}




  


                       
  

Note that this pauses the editor when ‘ErrorPause’ is enabled.

using UnityEngine;
using System.Collections;
public class MyGameClass : MonoBehaviour
{
    private Transform transform;
    void MyGameMethod()
    {
        if (transform == null)
            Debug.LogError("memberVariable must be set to point to a Transform.", transform);
    }
}

Note that this pauses the editor when ‘ErrorPause’ is enabled.

The most basic thing you can do in programming is print a string onto the console. Unity is the same: You can write a string to Unity Editor’s console, and there are different types of log messages and ways you can customize to make debugging easier.

The most common logging method is the Debug.Log() method which prints a regular string onto the console in Unity in the default text color. There are also 2 other types of log types called Debug.LogWarning() and Debug.LogError() that prints a string in yellow and red, respectively.

Knowing how to use the logging methods and how they interact with the Unity console will make your life much easier. Read more below to learn how to customize debug messages.

Table of Contents

• Debug.Log
• Debug.LogWarning
• Debug.LogError
• Debug.LogException
• Format Debug Log Messages with Rich Text Markup
• Composite Formatting
• Ending Thoughts

The Debug.Log is the most basic and the easiest way to print a value to the Unity console.

Simply supply it with a string or any value that can be converted into a string and it will display the message on the console.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        Debug.Log("This string will be printed to the console.");
    }
}




  


                       
  



Code language: C# (cs)

The result will look something like this in the console:

Clicking on the message will bring up a small details section that tells you about where the message comes from.

For example, the message in the image above is at line number 9 in the script named TestScript.

Additionally, the latest console message will also display at the bottom left corner of Unity Editor.

The Debug.Log method can print the value of anything as long as it can be converted into a string.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        float someNumber = 420.69f;
        bool isVeryCool = true;
        
        Debug.Log(someNumber);
        Debug.Log(someNumber + " BLAZE IT");
        Debug.Log(isVeryCool);
    }
}
Code language: C# (cs)

The code above will print 3 lines of messages to the Unity console:

You can also link a related game object to a console message to make it easier to find where the message comes from by passing an object as the second parameter of the Debug.Log method.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        int someNumber = 1234;
        
        Debug.Log("This is a number: " + someNumber, transform);
    }
}
Code language: C# (cs)

This will highlight the associated object in the hierarchy window when you click on the message in the console window.

Aside from logging messages to the Unity console, Debug.Log (and other logging methods) also logs messages to log files of your game. Information on where to find these log files for each platform can be found here.

Debug.LogWarning

The Debug.LogWarning works the same way as Debug.Log but the message printed will have a warning icon and the color of the message on the bottom left corner of the Unity Editor will be yellow instead.

This one is generally used to give a warning that something might not be working correctly or something is missing from the code but can still work. Something like that. You get the idea.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        Debug.LogWarning("Setting the width to more than 300px will result in a drop in performance.");
    }
}
Code language: C# (cs)

This will log a message with a warning icon to the console.

The warning message shown at the bottom left corner of Unity Editor will be yellow.

An object can also be passed to the method to link the object with the warning message, just like Debug.Log.

Debug.LogError

The Debug.LogError method behaves in the same way as the Debug.Log method and the Debug.LogWarning method, but the message logged to the Unity console will have an error icon and the message at the bottom of the editor will be red.

This logging method is commonly used for displaying code-breaking error messages to the console.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        Debug.LogError("Failed to initialize player's default parameters.");
    }
}




  


                       
  



Code language: C# (cs)

The message printed to the console will have an error icon attached to it.

The message shown at the bottom left corner of Unity Editor will have a dark red text color.

An object can also be passed to the method to link the object with the error message, just like Debug.Log.

Debug.LogException

The Debug.LogException is used to log exceptions to the Unity console. It works the same way as the regular Debug.LogError except you supply it with an exception object instead of a string.

You use this when you want the error to be more specific, or you want to capture an exception and print it to the console manually.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        Debug.LogException(
            new MissingComponentException(
                "RigidBody2D is missing in " + transform.gameObject.name +
                ". RigidBody2D is required for this script to work properly."
            ),
            transform
        );
    }
}
Code language: C# (cs)

This will log an exception to the console with an error icon.

This message will display as dark red text at the bottom left corner of the Unity Editor.

It might be a little hard to see as I’m using dark mode, but it’s there.

Format Debug Log Messages with Rich Text Markup

All Debug.Log variants can be further customized using rich text markup. You can do various things such as making a word bold or changing the color of a message.

The rich text markup’s syntax is similar to HTML markup but not entirely the same.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        Debug.Log("I do <b>NOT</b> like ducks.");

        Debug.LogWarning("Something <i>weird</i> might happen. Be careful.");

        Debug.LogError("This function stopped working <b><i>again</i></b>.");

        Debug.Log("<color=red>Red</color>/<color=blue>Blue</color>/<color=green>Green</color>");
    }
}
Code language: C# (cs)

If you’re familiar with HTML, this one should be easy to understand. For more information about the rich text, visit the Unity Rich Text Official Manual page.

Composite Formatting

All Debug.Log variants come with Format versions of themselves which allow more complex formatting called Composite Formatting.

These methods are:

• Debug.LogFormat
• Debug.LogWarningFormat
• Debug.LogErrorFormat

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    private void Start()
    {
        string[] names = { "Chloe", "Angelica", "Yufine", "Tamarinne" };
        float[] money = { 1250f, 777f, 240.5723f, 300f };

        for (int i = 0; i < names.Length; i++)
        {
            Debug.LogFormat("{0} | {1:C2}", names[i], money[i]);
        }
    }
}
Code language: C# (cs)

For more information about composite formatting, refer to MSDN documentation on Composite Formatting.

Ending Thoughts

Knowing how to log messages to the console in different ways can make your debugging process a lot easier, both to yourself and to those who work with you.

I recommend trying those logging methods out yourself in the editor so it’s easier to understand.

I hope this has been a good read for you. Leave a comment if you have suggestions or I’m missing something. And I’ll see you again in the next article!

Cheers!

Attribution

Console icon made by Freepik from www.flaticon.com

Logging is an essential part of a development setup and very useful in production to monitor app health. Unity is a popular cross-device game engine that uses Mono to run scripts written in C#. In this article, we will see how you can enable logging for unhandled exceptions and debug messages in a Unity application. Some of the behavior is the same as for general Mono applications but Unity adds more steps to the lifecycle of the application that needs to be taken into account. In the end we also look at how we can use this to log from a Unity application to elmah.io.

Existing logging solutions

The easiest method for logging in a local setting is definitely just to use the Unity IDE where you will then see any logs or exceptions in the console window. You can also build a version of your application that prints the console output directly in the app. These options are nice but not always possible or practical. If it is not possible to attach the debugger to the place that you run the application then you can’t use the Unity IDE to log errors. Then our other option is to add the in-app console log but this can fill much of the interface and you might not want the user to see your error log. Another problem is that we also want to do more than just see the errors separately. We want to collect the errors in our logging system.

Unity already has a system for cloud logging called Cloud Diagnostics. This is well-integrated into the Unity platform. But we would probably rather have the errors be logged to our existing error logging service instead of adding another platform to monitor our applications.

Application Lifecycle

Mono itself has the same entry point as the applications that we can create in .NET.

public class HelloWorld
{
    // Method is called when application is started.
    public static void Main(string[] args)
    {
        // Setup logging here.
    }
}

But Unity is a component-based framework and does not make it possible to create a Main function.

Instead, we need to add an empty component to the scene that we work with. It is a good idea to have the logging in a separate component so that you know that the component is alive throughout the whole lifetime of the application.

Then we can add a script to the component where we will set up logging.

In this, we can add the following methods that will get called during different lifecycle events in the component.

using UnityEngine;

public class Logging : MonoBehaviour
{
    // This function is always called before any Start functions
    void Awake()
    {
        
    }

    // Start is called before the first frame update
    void Start()
    {
        
    }

    // Update is called once per frame
    void Update()
    {
        
    }

    // This function is called after all frame updates for the last frame of the object’s existence
    void OnDestroy()
    {
        
    }
}

The important thing to note is that Awake is called before any Start function is called. So we will want to add the logging to the application in the Awake function. Doing this means that we can catch any error that is thrown in Start or Update where most of the workload is normally done. We can’t make any promises for what order Awake functions in different components are called, so it is generally a good idea to delay code that could throw errors from Awake until Start if possible.

Standard error handling in Unity

The code that you run in the Start and Update functions can tell the program that something went wrong in multiple ways. If the error is not critical to the further execution of the program then you can log an error with

Debug.LogError("Something went wrong");
Debug.LogWarning("Something went wrong");
Debug.LogException(new Exception("Something went wrong"));

If the execution is critical or if you want to enable the caller to handle exceptions through the call stack then you can throw an exception instead.

throw new Exception("Something really went wrong");

Often you don’t go around and create a lot of the logic yourself when developing Unity apps. But instead, use some implementation from the standard libraries. These standard libraries are a mix of wrappers for C++ libraries and natively developed .NET packages. There is not a universal rule for when a library uses either logging method so we will have to handle both scenarios.

Event Handler for Debug logs

We can subscribe to an event that is triggered every time something is logged with Debug like so.

void Awake()
{
    Application.logMessageReceivedThreaded += Application_logMessageReceivedThreaded;
}

private void Application_logMessageReceivedThreaded(string condition, string stackTrace, LogType type)
{
    // Log log to your logging system.
}

Then we can handle every time something logs an error of one of the following types (severities): Assert, Error, Exception, Log, Warning. We could even filter on this if we e.g only want to log Assert or Exception errors. This can be useful as the same error can occur in the body of the Update function every time it is called which can quickly run into the thousands when it is called every frame.

Event Handler for Unhandled Exceptions

We can also subscribe to the event of an unhandled error occurring. This can also be done in the Awake function.

void Awake()
{
    TaskScheduler.UnobservedTaskException += TaskScheduler_UnobservedTaskException;
}

private void TaskScheduler_UnobservedTaskException(object sender, UnobservedTaskExceptionEventArgs e)
{
    // Log `e.Exception` to you logging system
}

We can get much more detail about the exception and the context that it occurred in when we have an Exception object. It looks like Unity catches all Exceptions that are thrown in non-async threads. So these will be handled by the Debug logger, but all Exceptions that are thrown in a Task will instead be caught by the UnobservedTaskException event handler.

Unsubscribing events

It is a good idea to also unsubscribe to events once the application closes but not strictly necessary as the application is about to close anyway. We do this in the counterpart to the Awake function in the lifecycle which is OnDestroy.

// This function is called after all frame updates for the last frame of the object’s existence
void OnDestroy()
{
    Application.logMessageReceivedThreaded -= Application_logMessageReceivedThreaded;
    TaskScheduler.UnobservedTaskException -= TaskScheduler_UnobservedTaskException;
}

Logging to elmah.io from Unity

We have the capability to get all relevant information about logs and exceptions. So now, we just have to log it to our cloud logging service of choice. Not to be biased but for me, that’s elmah.io. So let’s see how we can do that. The following will use the newest preview version of the Elmah.Io.Client package.

You can’t add packages from Nuget to a Unity project directly but you can download the dll files and add them manually. So I simply went to
https://nuget.org/packages/Elmah.Io.Client selected the newest preview version and clicked Download package.
This gives us a .nupkg file that we can simply rename to .zip and open using the file explorer. In this, we will see a lib folder that contains all the versions that this package targets. We need the netstandard2.0 version as Unity is compatible with this version. So we just copy the files in that folder and paste them into a new folder Libraries in the Assets folder of our Unity project. Elmah.Io.Client almost only uses the standard libraries but still has a single dependency on Newtonsoft.Json. So we just need to do the same for the Newtonsoft.Json package and add its dll’s to the Libraries folder. When dll’s are placed within the Assets folder then Unity will automatically add them during the build process.

Now that we have the package installed then we can begin to log messages.

We first add an IElmahIoAPI property to the component so that we don’t need to instantiate a new every time we log.

private IElmahioAPI api;

Then we can start by logging Debug logs

private void Application_logMessageReceivedThreaded(string condition, string stackTrace, LogType type)
{
    if (api == null)
    {
        api = ElmahioAPI.Create("API_KEY");
    }

    Severity severity = Severity.Debug;
    switch (type)
    {
        case LogType.Assert:
            severity = Severity.Information;
            break;
        case LogType.Error:
            severity = Severity.Error;
            break;
        case LogType.Exception:
            severity = Severity.Error;
            break;
        case LogType.Log:
            severity = Severity.Verbose;
            break;
        case LogType.Warning:
            severity = Severity.Warning;
            break;
    }

    var message = new CreateMessage()
    {
        Title = condition,
        Detail = stackTrace,
        Severity = severity.ToString(),
        Url = Application.absoluteURL
    };

    api.Messages.Create("log-id", message);
}

We don’t really have a lot of information when logging from Debug but we do have a log type that is somewhat equivalent to our log severity, so we switch on the log types and assign each a severity. This is only an attempt at mapping but it still gives a lot of information.

Next, we also want to log unhandled exceptions and we do this like like the following which is very close to how we would log Exceptions manually in other frameworks:

private void TaskScheduler_UnobservedTaskException(object sender, UnobservedTaskExceptionEventArgs e)
{
    if (api == null)
    {
        api = ElmahioAPI.Create("API_KEY");
    }

    var exception = e.Exception;
    var baseException = exception?.GetBaseException();

    var message = new CreateMessage()
    {
        Data = exception?.ToDataList(),
        DateTime = DateTime.UtcNow,
        Detail = exception?.ToString(),
        Severity = "Error",
        Source = baseException?.Source,
        Title = baseException?.Message ?? "Unhandled Unity exception",
        Type = baseException?.GetType().FullName,
    };

    api.Messages.Create("log-id", message);
}

Testing the integration

Now let’s provoke one of the most common errors Object reference not set to an instance of an object which we have also blogged about before Debugging System.NullReferenceException — Object reference not set to an instance of an object

We provoke the Exception with the following in our Start function.

private List<string> list { get; set; }

// Start is called before the first frame update
void Start()
{
    list.Add("Hello");
}

There will be thrown an Exception when we try to add "Hello" to the list as the list is not initialized yet.
This Exception is not thrown in an asynchronous thread so the Debug logger will observe it and we will log the error through the logMessageReceivedThreaded event handler.

This example can be found at https://github.com/elmahio-blog/Elmah.Io.UnityExample.

If we instead change the Start function to be asynchronous in a Task then we would see it be handled by the UnobservedTaskException event handler

private List<string> list { get; set; }

// Start is called before the first frame update
async Task Start()
{
    list.Add("Hello");
}

So now we have successfully added logging to elmah.io from a Unity application and seen that it works.

Conclusion

In this article, we have looked at existing Unity logging solutions. Then we have seen how we can log errors for the full life time of an application in general. In the end, we looked at how we can use this to log Exceptions and Debug Messages to elmah.io.

See how we can help you monitor your website for crashes
Monitor your website

Параметры

Описание

Записывает сообщение в консоль Unity.

Используйте Debug.Log для печати информационных сообщений, помогающих отлаживать приложение. Например, вы можете напечатать сообщение, содержащее GameObject.name и информацию о текущем состоянии объекта.

Вы можете форматировать сообщения с помощью объединения строк:
Debug.Log("Text: " + myText.text);

Вы также можете использовать разметку Rich Text.

Если вы передаете GameObject или Component в качестве дополнительного контекста аргумент, Unity мгновенно выделяет этот объект в окне Иерархия, когда вы щелкаете сообщение журнала в Консоли. Используйте объект context, когда у вас есть много экземпляров объекта в сцене, чтобы вы могли определить, какой из них создал сообщение. Пример 2 ниже иллюстрирует, как работает эта функция. При запуске этого примера сначала щелкните один из
кубы, которые он создает в сцене. В этом примере сообщение журнала печатается в Console. Когда вы нажимаете на сообщение, Unity выделяет объект context в окне Hierarchy — в данном случае куб, на который вы нажали в сцене.

Пример 1. Покажите некоторые примеры использования Debug.Log:

using UnityEngine;
using System.Collections;

// Message using rich text.
Debug.Log("Error: AssetBundle not found");
}
}


Пример 2. Показать выделение нажатого GameObject:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

if (Physics.Raycast(ray, out hit))
{
// Visit each cube and determine if it has been clicked.
for (int i = 0; i < 3; i++)
{
if (hit.collider.gameObject == cubes[i])
{
// This cube was clicked.
Debug.Log("Hit " + cubes[i].name, cubes[i]);
}
}
}
}
}
}


Обратите внимание, что Unity также добавляет сообщения Debug.Log в файлы журнала редактора и проигрывателя. Дополнительные сведения о доступе к этим файлам на разных платформах см. в разделе Файлы журнала.

Debugging in Unity can be a very simple thing to do.

In fact, even if you’re still new to Unity, you’ve probably already used Debug Log to send basic messages to the Console.

Which is useful, as being able to trigger messages from your scripts can be a great way to understand what’s happening behind the scenes.

However…

While using Debug Log to display a single message in the Console can be very straightforward, knowing how to use Unity’s debugging tools to manage an entire project can be much more challenging.

For example, how can you tell the difference between good log messages, that confirm that things are working properly, from bad ones, that can tell you that something’s gone wrong?

How can you manage different categories of debug messages, and avoid cluttering your Console with information about old work that you’ve already finished?

And when your game is done, how can you easily turn off some or all of your debug messages, to prevent them from negatively impacting your game’s performance?

There’s a lot to consider, but don’t worry, because in this article you’ll learn the basics of debugging in Unity, how you can use Unity’s debugging tools to your advantage and how to easily manage your debug messages as you go.

Here’s what you’ll find on this page:

• How to use Debug Log in Unity
• How to format Debug Log messages in Unity
• The best way to use Debug Log
• How to disable Debug Log messages in Unity

Let’s get started.

The simplest way to print a message in the console in Unity is by using the Debug Log function, which takes a string value and displays it in the Console window.

Like this:

void Start()
    {
        Debug.Log("Hello World");
    }

Which, in the Console, looks like this:

In its most basic form, Debug Log prints a single message, that will be shown in the Console when that line of code gets executed.

However, while what you see in the Console is a simple string, you can pass in just about anything you like.

For example, a float value:

float health = 100;
void Start()
{
    Debug.Log(health);
}

Which can be useful for checking the value of a variable at a specific time.

Like this:

An object or property reference:

void Start()
{
    Debug.Log(gameObject.name);
}

Which, in this case, gets the name of the object that the script is attached to.

Which, in the Console, looks like this:

A conditional value:

void Start()
{
    Debug.Log(1 + 1 == 2);
}

Which, in the Console, returns a true or false statement depending on the result of the conditional check.

Like this:

Or a mixture of text and variables:

float health = 100;
void Start()
{
    Debug.Log("Player Health: " + health);
}

Which allows you to add any combination of text and variable data to a Console message.

And looks like this:

How to connect a Debug Log message with a specific object

While the basic method of using Debug Log displays a message in the Console, it’s also possible to provide a reference to an Object that the message may relate to.

For example, you could pass in a reference to the game object that the script is attached to.

Like this:

float health = 100;
void Start()
{
    // Logs the player's health, with a reference to this game object.
    Debug.Log("Player Health: " + health, gameObject);
}

Then, in the Unity Editor, clicking on the message in the Console will show you exactly which object it relates to.

Like this:

This can be useful for working out which object is associated with a specific message or error, particularly if it could have been generated from any one of a number of duplicated objects.

print("This is a print message");

How to use Debug Warning and Debug Error

While Debug Log can be useful for displaying information about what’s happening in your game, it’s also possible to use the Debug Console to display your own warnings and errors as well.

This works by using the Log Warning and Log Error functions.

Like this:

void Start()
    {
        Debug.Log("This is a basic log message");
        Debug.LogWarning("This is a basic warning message");
        Debug.LogError("This is a basic error message");
    }

Which, in the Console, will appear as errors and warnings, just like the ones that are generated by Unity.

Like this:

This can be useful for raising different types of notification, instead of just basic messages, and can be particularly helpful when you want to distinguish between informational logs and an alert that something is not working in the way that it’s supposed to.

For example, you could use a warning to remind yourself that a particular script hasn’t been set up properly, or an error to catch a mistake that you know will cause a problem.

Log Messages, Warnings and Errors can each be shown or hidden by using the filtering tools available in the top right-hand corner of the Console.

Using different categories of messages can help you to find problems in your game more easily.

But, that can sometimes be difficult to do when you’re not sure when an error has occurred and what else was happening at the time.

So how can you debug your game in a way that makes catching problems easier to do.

How to use debug messages to check for problems

One basic method of catching issues as they happen is to enable Error Pause in the Console.

This will pause the Unity Editor when an error occurs which can make it significantly easier to work out what the cause was.

However, that’s not the only way you can pause the Editor using debug messages.

Debug Break, for example, allows you to deliberately pause the Unity Editor at a specific moment in time:

Debug.Break();

This can be useful for diagnosing problems or checking data that would be difficult to see while the game runs at full speed.

Lastly, Debug Assert can be used to double-check if what you expected to happen in a script actually did.

This works by passing in a conditional value to the Assert function, that will either be true or false, along with a message, that can be used to describe the problem.

For example:

public int one = 1;
public int two = 2;
public int three = 3;
void Start()
{
    Debug.Assert(one + two == three, "1 plus 2 did not equal 3");
}

The Debug Assert function expects the conditional value to be true and, if it’s not, an error will be raised, using the message that’s passed in.

This can be useful for double-checking what you think you know, or testing to see if variable data is what you thought it was going to be.

By default, Debug Assert assumes that the conditional value that you pass in is meant to be true.

However, there may be times when you want to check that something is false, that two things are not the same or that two float-based values, which can be difficult to directly compare, are roughly equal or not.

Luckily, the Assert Class provides a number of additional comparison functions that allows you to do exactly that and to check that a value or a method is doing what it’s meant to do.

public class VisualDebugging : MonoBehaviour
{
    public Transform otherCube;
    void Update()
    {
        // Draws a line between the object and the other cube
        Debug.DrawLine(transform.position, otherCube.transform.position);
    }
}

public class VisualDebugging : MonoBehaviour
{
    void Update()
    {
        // Draws a 10 unit long line in the Scene view going up
        Debug.DrawRay(transform.position, Vector3.up * 10);
    }
}

How to format Debug Log messages in Unity

Once you’re familiar with how to print a message to the Console in Unity, you might want to format how that message is displayed.

The dotted menu icon at the top right of the Console, allows you to hide some of the additional information that you may not always need but that is provided by default.

It also allows you to change the number of lines used to display each entry.

Which can make reading the Console much easier to do at a glance:

But that’s not all.

While Unity provides a number of filtering and display options in the Console window, it’s possible to format the actual text that is displayed in the message, using Rich Text Formatting.

Which can be used to change the size, emphasis and even the colour of text in the Debug Console window.

How to change the colour of Debug Log messages in the Console

To change the colour of the text in a Debug Log message, simply wrap the text you’d like to highlight with a Color Tag.

Like this:

Debug.Log("<color=red>This is a red message</color>");
Debug.Log("<color=blue>This is a blue message</color>");
Debug.Log("This is <color=red>red</color> & <color=blue>blue</color>");
Debug.Log("<color=#cd542a>This is my favourite shade of orange</color>");

The Color Tag accepts colours defined by specific names, such as red, blue or magenta as well as hex values.

It’s also possible to make the text in a Debug Log message bold, italic or even change its size.

How to make Debug Log text bold, italic or create new lines

To change the formatting of the Debug Console text, simply add tags before and after whatever text you’d like to format.

Like this:

Debug.Log("<b>This is bold.</b>");
Debug.Log("<i>This is italic</i>");
Debug.Log("<size=25>This Text is BIG</size>");
Debug.Log("<size=5>This Text isn't</size>");

It’s even possible to create new lines using the new line character. 

Like this:

Debug.Log("This is a n new line.");

For more information on how to format Console messages in Unity, see the official documentation here.

string playerName = "Keith";
float health = 100;
void Start()
{
    Debug.LogFormat("{0}'s Health is {1}", playerName, health);
}

void WhatsTheTime()
{
    float minutes = Mathf.FloorToInt(Time.realtimeSinceStartup / 60);
    float seconds = Mathf.FloorToInt(Time.realtimeSinceStartup % 60);
    Debug.LogFormat("The game has been running for {0:00}:{1:00}", minutes, seconds);
}

The best way to use Debug Log

Debug Log is an extremely useful feature of Unity that allows you to understand what’s happening behind the scenes of your game in an easy and simple way.

However…

While the Debug Log function might appear to be simple and lightweight, it can actually be very slow and, depending on how you’re using Debug Log in your game, can cause significant performance issues.

This happens because Debug Log writes every message to an actual file, on your computer’s hard disk, which can be a slow operation to perform.

What’s more, the Debug Log function creates garbage which, if used frequently or excessively, can lead to stuttering and hitches in gameplay as it’s collected.

While this isn’t necessarily a problem when you’re working on your game, it might surprise you to know that debug messages will be included, and called, in your finished build by default.

Meaning that every Debug Log, Warning and Error function that you use while you’re building your game will be also be called, and logged, in your finished game too.

In some cases, this might be exactly what you want. 

After all, the purpose of logging information is so that you can use it to identify problems.

However, if you’re using Debug Log excessively in your project, it can cause a noticeable drop in performance.

For this reason, it can be a good idea to use Debug Log sparingly and to avoid calling it frequently in Update.

However, depending on how much you’ve used Debug Log, you might want to completely disable log messages in your finished game.

So how can you turn Debug Log off? 

How to disable Debug Log messages in Unity

Because of the potential performance impact of using Debug Log in your game, you may wish to turn off some or all debugging in your finished project.

There are a number of ways you could do this.

For example, it’s possible to exclude certain code from being used in built games with Platform Dependent Compilation.

Like this:

#if UNITY_EDITOR
     Debug.Log("This will only be included in the Editor");
 #endif

This will mean that code inside of the conditional statement simply won’t be compiled if the platform doesn’t match, which can be useful for running platform-specific debugging or for turning it off altogether.

However,

While checking if the game is running in the Editor or in a standalone build will work, it’s not a convenient option and, if you’re using multiple Debug Log messages throughout your code, wrapping each one with a conditional statement can be time-consuming and can clutter up your scripts.

So what are the alternatives?

How can you turn off some or all of the debugging in your game, without adding conditional checks to every Debug Log call in every script?

Option 1: Disable the Player Log

In Project Settings, under the Player Tab, you’ll find an option to disable the Player Log, which is the file that Debug Log writes to when it’s called.

This can dramatically improve performance as, writing to a file, compared to most game functions, can be an extremely slow process.

However, while this will improve performance dramatically, by removing the need to write each log entry to disk, Debug Log will still be called and, as a result, will still generate garbage, which can cause performance issues.

If you’re only occasionally calling Debug Log, this might not be a problem for you.

But, if you’re using Debug Log frequently, from many different objects, you may start to notice stuttering and hitches as garbage is collected.

In which case, turning off the Player Log doesn’t make a lot of sense, as you’d still be sacrificing part of your game’s performance with no real benefit.

So what else can you do?

Option 2: Use a custom Debug function

One option for disabling log messages in your finished project is to create a custom debug function inside a static class and then wrap that in a conditional check.

Like this:

public static class GameLog
{
    public static void LogMessage(string message)
    {
        #if UNITY_EDITOR
        Debug.Log(message);
        #endif
    }
    public static void LogWarning(string message)
    {
        #if UNITY_EDITOR
        Debug.LogWarning(message);
        #endif
    }
    public static void LogError(string message)
    {
        #if UNITY_EDITOR
        Debug.LogWarning(message);
        #endif
    }
}

Then whenever you want to use Debug Log, simply call your custom function instead of the standard Debug method.

Like this:

GameLog.LogMessage("This is a custom Log Message!");

This makes it possible to exclude debug messages from your finished game, but without needing to wrap every debug method in its own compilation check.

This works, and can be a useful way to manage excessive logging in your game so that it doesn’t hurt performance.

However, this method can still cause performance problems in your game, depending on how you’re using log messages.

This is because, while the content of the function is wrapped in a conditional check, the function itself can still be called.

Which, while this prevents the large performance overhead of using Debug Log, doesn’t avoid the potential to create garbage when defining its contents.

If you’re just using simple strings in your log messages, then this may not be a problem for you as, even though the function is still being called, surprisingly, no garbage is generated.

However, if you combine two strings together, as you’re likely to do when introducing game data to a debug message, the string concatenation process will create garbage, even though the function is, essentially, empty.

To avoid this, it’s possible to make the method itself conditional, meaning that it, and any calls to it, will not be compiled unless a define symbol exists, such as the UNITY_EDITOR symbol.

Like this:

[System.Diagnostics.Conditional("UNITY_EDITOR")]
    public static void LogMessage(string message)
    {
        Debug.Log(message);
    }

Or you can use a custom symbol, in which case you’ll need to enable it by adding the define preprocessor directive to the top of the script.

Like this:

#define MYSYMBOL
using UnityEngine;
public class MyClass : MonoBehaviour
{
    void Start()
    {
        GameLog.LogMessage("This will only appear if the define symbol is set!");
    }
}

This is one of the best methods for removing debug messages from a finished game because it excludes the message function and the call to it, avoiding garbage^*.

What’s more, it allows you to easily enable or disable messages globally.

However, this may not be as useful to you if you’ve already added a large number of log messages to your game using Unity’s existing Debug Log function.

So how can you turn off debug messages, without using custom functions?

Option 3: Disable the Unity Logger

An easy way to disable all Debug Log functions in Unity is to simply turn off the Unity Logger.

This works by setting the Log Enabled property of the Logger to false.

Debug.unityLogger.logEnabled = false;

This works in the Editor and in standalone builds of the project and prevents all debug messages from being called, saving performance and avoiding garbage.

Typically, however,  you might only want to disable debug messages in your finished project, in which case it’s possible to enable or disable the Logger depending on if the project is a Debug Build or not.

Like this:

private void Awake()
{
    Debug.unityLogger.logEnabled = Debug.isDebugBuild;
}

This means that log messages will only be called in the Editor and in a build of the game if it’s marked as a development build.

However, what if you only want to disable some, but not all, log messages.

For example, you might want to keep certain messages, such as warnings and errors, in the log, so that you know if something went wrong in the build of your game.

Or you might want to disable messages relating to a particular feature that were useful while you were working on it, but are, now, just cluttering up the Console.

How can you categorise different messages into groups so that you can turn some of them off but leave others on?

How to turn off some, but not all, Debug Log messages in Unity

In the same way that it’s possible to disable the default Unity Logger, it’s possible to create new Logger instances, that can be used to categorise log messages into different groups, and then turn them on or off as you like.

This is useful, as it allows you to separate the messages that you use during development from the errors and the warnings that you might need to be able to check for in a build.

Here’s how it works.

To make a new Logger, create a new Logger instance that is public and static so that any script can access it.

Like this:

public static class Logging
{
    public static Logger myLogger = new Logger(Debug.unityLogger.logHandler);
}

To initialise the Logger instance, you’ll need to pass in a Log Handler, which manages saving log messages to a file on your computer’s hard drive.

In this example, I’m using the same Log Handler as the default Logger, meaning that, even though the log messages can be enabled or disabled separately, they’ll still be written to the same log file.

Once you’ve created a new Logger, you can use it to create debug messages with the Logger’s Log function, which works in the same way as Debug Log does.

Like this:

Logging.myLogger.Log("This message uses my custom Logger");

Setting up your own Loggers in this way allows you to enable or disable specific logging functions in your finished game and in the Editor.

For example, you could create different logging categories for combat, for your player, or for any other feature that might require extensive logging but that you’d like to have the option of turning off later on.

For this to work, create new Loggers for any categories of logging that you want to be able to separate and create a static function, in the same class (so that it’s easy to find and modify), that will specify if they are enabled or disabled.

public static class Logging
{
    public static Logger combatLogger = new Logger(Debug.unityLogger.logHandler);
    public static Logger playerLogger = new Logger(Debug.unityLogger.logHandler);
    public static void LoadLoggers()
    {
        // Call this function when the game starts
        combatLogger.logEnabled = true;
        playerLogger.logEnabled = true;
    }
}

Then, to set your debugging preferences, call the Load Loggers function when the first Scene loads.

Like this:

public class LoadLoggers : MonoBehaviour
{
    private void Awake()
    {
        Logging.LoadLoggers();
    }
}

Enabling or disabling groups of log messages in this way can be an efficient method for managing debug functions in your game.

However, while this method prevents the processing and garbage overheads of using the Debug Log function, just like when using conditional statements inside of a function, it doesn’t prevent garbage from being created when it’s called.

Meaning that, if you’re passing concatenated strings to the Debug Log function, it will still create some garbage.

As a result, if it’s an option for you, the best method for managing debug messages inside of a finished game is to exclude them from compilation entirely, by calling a custom function with a conditional attribute.