Logging in Unreal

When debugging, logs are an invaluable tool that provide detailed information on what logic your code is executing. You can inspect data values passed between functions, and report potential issues.

• Logging in Unreal provides several ways to keep an ordered record of events, function calls, and values of variables at any particular moment during runtime.

• You can observe your logs in the Unreal Editor by navigating to Window > Output Log.

• Logs are saved in a .txt file in your project's Saved/Logs directory

UE_LOG

UE_LOG is a macro that logs a formatted message into the log file.

For example:

UE_LOG(LogTemp, Warning, TEXT("Hello World"));

• The first input parameter LogTemp is the Category Name as provided to the DEFINE_LOG_CATEGORY macro. You can find these categories in the engine located in CoreGlobals.h. To create your own custom logging categories, see the Define your own log category section.

• The second input parameter Warning is a Verbosity level that is used to print a warning to the console and the log file. You can set varying verbosity levels to allow line breaks in a given log or set the log text color. See the Log Verbosity section for additional details.

• The third input parameter Text is the format of the string literal in the style of the C language library function printf.

Log Verbosity

ELogVerbosity is an enum that defines the verbosity levels of the logging system. It defines additional non-verbosity levels that allow breaking on a given log line or setting the color of the log text.

VeryVerbose,
NumVerbosity,
VerbosityMask   = 0xf,
SetColor        = 0x40, // not actually a verbosity, used to set the color of an output device 
BreakOnLog      = 0x80

Console Commands

It's possible to change the verbosity of different log categories from the command line using -LogCmds=

For example:

    -LogCmds="LogDerivedDataCache Verbose"  

This command lets you specify multiple categories, including an "all" category that toggles every log category to a specific verbosity level.

Logging Fundamental Data Types

The table below provides some syntax formatting examples on how to log a particular data type.

UE_LOG(LogTemp, Warning, TEXT("An Actor's name is %s"), *ExampleActor->GetName());

UE_LOG(LogTemp, Warning, TEXT("The boolean value is %s"), ( bExampleBool ? TEXT("true"): TEXT("false") ));

UE_LOG(LogTemp, Warning, TEXT("The integer value is: %d"), ExampleInteger);

UE_LOG(LogTemp, Warning, TEXT("The float value is: %f"), ExampleFloat);

UE_LOG(LogTemp, Warning, TEXT("The vector value is: %s"), *ExampleVector.ToString());

UE_LOG(LogTemp, Warning, TEXT("Current values are: vector %s, float %f, and integer %d"), *ExampleVector.ToString(), ExampleFloat, ExampleInteger);

Define Your Own Log Category

You can define your own log category and use it in your C++ code example. This might be beneficial if your examples include multiple files or frameworks that require distinct categorization. In the relevant header file, add the following just below the include directives:

DECLARE_LOG_CATEGORY_EXTERN(<LOG_CATEGORY>, <VERBOSITY_LEVEL>, All);

where <LOG_CATEGORY> is your custom log category string and is one of the following table values:

Log verbosity levels

In the relevant C++ file, add the following just below the include directives:

DEFINE_LOG_CATEGORY(<LOG_CATEGORY>);

Now you can use this category in your C++ file code as:

UE_LOG(<LOG_CATEGORY>, <VERBOSITY_LEVEL>, TEXT("My log string."));

UE_LOGFMT

UE_LOGFMT records a structured log event that supports Positional or Named parameters but can not mix both styles. To use this macro you, need to include the Logging/StructeredLog.h library declaration.

UE_LOGFMT(LogCore, Warning, "Loading `{Name}` failed with error {Error}", Package->GetName(),  ErrorCode);

UE_LOGFMT(LogCore, Warning, "Loading `{Name}` failed with error {Error}",("Name", Package->GetName()), ("Error", ErrorCode),("Flags", LoadFlags));

On-screen debug messages

Another useful method of communicating information is through on-screen debug messages. You can add an on-screen debug message with the following code:

if (GEngine)
{
    GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::White, TEXT("This is an Example on-screen debug message."));
}

• The first input parameter key takes a unique integer key to prevent the same message from being added multiple times.

• The second input parameter TimeToDisplay takes a float for how many seconds to display the message before it fades away.

• The third input parameter DisplayColor takes a color to display the text in.

• The fourth input parameter DebugMessage is the message to display. You can use format specifiers and variables in on-screen debug messages similar to logs.