Logs: Printing Messages to Yourself during Runtime

UE4: Guidebook
Search…
UE4: Guidebook
4.24
Introduction
Quick Reference
Wiki Archives
Debugging & Utilities
Exec Functions
How To Prevent Crashes Due To Dangling Actor Pointers
Profiling: How to Count CPU Cycles
Logs: Printing Messages to Yourself during Runtime
Logs: Printing Messages to Yourself during Runtime
This wiki article was written by Rama; Converted by jfaw.
Overview
Dear Community,
Logs are essential for giving yourself feedback as to whether
Your new functions are even being called
What data your algorithm is using during runtime
Reporting errors to yourself and the end user / debugging team
Imposing a fatal error to stop runtime execution in special circumstances
This page describes how to use the Unreal output log.
Other options are also discussed at the bottom of the page.
Accessing Logs
In-Game
To see logs you must run your game with -Log (you must create a shortcut to the Editor executable and add -Log to the end).
or use console command "showlog" in your game.
Within Editor (Play-In-Editor)
Log messages are sent to the 'Output' log which is accessible via Window -> Developer Tools -> Output Log.
If you are using the Editor and PIE, logging should be enabled by default due to the presence of GameCommandLine=-log in your Engine INI file. If no logging is visible, add the -Log command line option as per the instructions for In-Game logging above.
Quick Usage
1
UE_LOG(LogTemp, Warning, TEXT("Your message"));
Copied!
This way you can log without the need of creating a custom category. Doing so will keep everything clean and sorted though.
Log Verbosity Levels
Log verbosity levels are used to more easily control what is being printed, allowing you to keep even the most detailed log statements in your code without having them spam output when you don't want them to. Each log statement declares which log it belongs to and it's verbosity level. Verbosity level is controlled on a per-log basis.
Each log's verbosity is controlled by four things: 1. Compile-time verbosity 2. Default verbosity 3. .ini verbosity 4. Runtime-verbosity.
If a log statement is more verbose than it's log's compile time verbosity it won't even be compiled into the game code. From there the log's level is set to the default verbosity, which can then be overridden in the Engine.ini file, either of those can then be overridden from the command line (the runtime verbosity). Once the game (or editor) is running it may not be possible to change a log category's verbosity (I am not sure, someone who knows please correct this).
Here are the verbosity levels available to use:
Fatal Fatal level logs are always printed to console and log files and crashes even if logging is disabled.
Error Error level logs are printed to console and log files. These appear red by default.
Warning Warning level logs are printed to console and log files. These appear yellow by default.
Display Display level logs are printed to console and log files.
Log Log level logs are printed to log files but not to the in-game console. They can still be viewed in editor as they appear via the Output Log window.
Verbose Verbose level logs are printed to log files but not the in-game console. This is usually used for detailed logging and debugging.
VeryVerbose VeryVerbose level logs are printed to log files but not the in-game console. This is usually used for very detailed logging that would otherwise spam output.
For the CompileTimeVerbosity parameter of DECLARE_LOG_CATEGORY_EXTERN it is also valid to use All (functionally the same as using VeryVerbose) or NoLogging (functionally the same as using Fatal).
Setting Up Your Own Log Category
Log Category Macros
The macros DECLARE_LOG_CATEGORY_EXTERN and DEFINE_LOG_CATEGORY go in YourGame.h and YourGame.cpp respectively.
The macro to declare a log category has three parameters. Each declared log category should have a corresponding defined log category in a cpp.
1
DECLARE_LOG_CATEGORY_EXTERN(CategoryName, DefaultVerbosity, CompileTimeVerbosity);
Copied!
CategoryName is simply the name for the new category you are defining.
DefaultVerbosity is the verbosity level used when one is not specified in the ini files or on the command line. Anything more verbose than this will not be logged.
CompileTimeVerbosity is the maximum verbosity to compile in the code. Anything more verbose than this will not be compiled.
The macro to define a log category takes only the name of the category.
1
DEFINE_LOG_CATEGORY(CategoryName);
Copied!
Usage Example
You can have different log categories for different aspects of your game!
This gives you additional info, because UE_LOG prints out which log category is displaying a message.
Here is an example of where the different log levels start to become useful.
Say you're often having trouble with a certain system in your game. In debugging you might want very detailed logs, but when you've finished debugging for now you know you might need those detailed logs later on, but they're spamming the output. What do you do? Use different log levels.
MyGame.H
1
//General Log
2
DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);
3
​
4
//Logging during game startup
5
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameInit, Log, All);
6
​
7
//Logging for your AI system
8
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameAI, Log, All);
9
​
10
//Logging for a that troublesome system
11
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSomeSystem, Log, All);
12
​
13
//Logging for Critical Errors that must always be addressed
14
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameCriticalErrors, Log, All);
Copied!
MyGame.CPP
1
#include "MyGame.h"
2
​
3
//General Log
4
DEFINE_LOG_CATEGORY(LogMyGame);
5
​
6
//Logging during game startup
7
DEFINE_LOG_CATEGORY(LogMyGameInit);
8
​
9
//Logging for your AI system
10
DEFINE_LOG_CATEGORY(LogMyGameAI);
11
​
12
//Logging for some system
13
DEFINE_LOG_CATEGORY(LogMyGameSomeSystem);
14
​
15
//Logging for Critical Errors that must always be addressed
16
DEFINE_LOG_CATEGORY(LogMyGameCriticalErrors);
Copied!
MyClass.CPP
1
//...
2
void UMyClass::FireWeapon()
3
{
4
    UE_LOG(LogMyGameSomeSystem, Verbose, TEXT("UMyClass %s entering FireWeapon()"), *GetNameSafe(this));
5
    //Logic
6
    UE_LOG(LogMyGameSomeSystem, Verbose, TEXT("UMyClass %s Attempting to fire."), *GetNameSafe(this));
7
    if (CheckSomething())
8
    {
9
        UE_LOG(LogMyGameSomeSystem, Log, TEXT("UMyClass %s is firing their weapon with charge of %f"), *GetNameSafe(this), GetCharge());
10
        //Firing logic
11
    }
12
    else
13
    {
14
        UE_LOG(LogMyGameSomeSystem, Error, TEXT("UMyClass %s CheckSomething() returned false during FireWeapon(), this is bad!"), *GetNameSafe(this));
15
        //Fail with grace
16
    }
17
    //More code!
18
    UE_LOG(LogMyGameSomeSystem, Verbose, TEXT("UMyClass %s leaving FireWeapon()"), *GetNameSafe(this));
19
}
20
​
21
void UMyClass::Tick(float DeltaTime)
22
{
23
    UE_LOG(LogMyGameSomeSystem, VeryVerbose, TEXT("UMyClass %s's charge is %f"), *GetNameSafe(this), GetCharge());
24
    if (something)
25
    {
26
        UE_LOG(LogMyGameSomeSystem, VeryVerbose, TEXT("Idk"));
27
    }
28
    if (somethingelse)
29
    {
30
        UE_LOG(LogMyGameSomeSystem, VeryVerbose, TEXT("Stuff"));
31
    }
32
}
33
//...
Copied!
When you're not working on this system all these log statements would absolutely flood your output, and even when you are working on it you might not want the level of detail that is putting out multiple logs per tick.
By using log levels you can simply change the verbosity in the category's declaration, in the ini files, or on the command line to hide/reveal different layers of log statements as you need them. Ex:
1
//All log statements are shown.
2
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSomeSystem, Log, All);
3
​
4
//VeryVerbose statements won't be shown.
5
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSomeSystem, Verbose, All);
6
​
7
//Neither VeryVerbose nor Verbose statements will be shown.
8
DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSomeSystem, VeryVerbose, All);
Copied!
The log categories used by Unreal Engine use different log levels, but by default have a higher CompileTimeVerbosity. In debugging interaction with Unreal code it might be helpful to turn up the verbosity of Unreal code in DefaultEngine.ini under [Core.Log] by adding an entry like LogOnline=Verbose.
Log Formatting
Log Message
1
//"This is a message to yourself during runtime!"
2
UE_LOG(YourLog,Warning,TEXT("This is a message to yourself during runtime!"));
Copied!
Log an FString
%s strings are wanted as TCHAR* by Log, so use *FString()
1
//"MyCharacter's Name is %s"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's Name is %s"), *MyCharacter->GetName() );
Copied!
Log an Bool
1
//"MyCharacter's Bool is %s"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's Bool is %s"), (MyCharacter->MyBool ? TEXT("True") : TEXT("False")));
Copied!
Log an Int
1
//"MyCharacter's Health is %d"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's Health is %d"), MyCharacter->Health );
Copied!
Log a Float
1
//"MyCharacter's Health is %f"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's Health is %f"), MyCharacter->Health );
Copied!
Log an FVector
1
//"MyCharacter's Location is %s"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's Location is %s"), 
3
    *MyCharacter->GetActorLocation().ToString());
Copied!
Log an FName
1
//"MyCharacter's FName is %s"
2
UE_LOG(YourLog,Warning,TEXT("MyCharacter's FName is %s"), 
3
    *MyCharacter->GetFName().ToString());
Copied!
Log an FString,Int,Float
1
//"%s has health %d, which is %f percent of total health"
2
UE_LOG(YourLog,Warning,TEXT("%s has health %d, which is %f percent of total health"),
3
    *MyCharacter->GetName(), MyCharacter->Health, MyCharacter->HealthPercent);
Copied!
Log Coloring
Log: Grey
1
//"this is Grey Text"
2
UE_LOG(YourLog,Log,TEXT("This is grey text!"));
Copied!
Warning: Yellow
1
//"this is Yellow Text"
2
UE_LOG(YourLog,Warning,TEXT("This is yellow text!"));
Copied!
Error: Red
1
//"This is Red Text"
2
UE_LOG(YourLog,Error,TEXT("This is red text!"));
Copied!
Fatal: Crash for Advanced Runtime Protection
You can throw a fatal error yourself if you want to make sure that certain code never runs.
I have used this myself to help protect against algorithm cases that I wanted to make sure never occurred again.
It's actually really useful!
But it does look like a crash, and so if you use this, dont be worried, just look at the crash call stack :)
Again this is an advanced case that crashes the program, use only for extremely important circumstances.
1
//some complicated algorithm
2
if(some fringe case that you want to tell yourself if the runtime execution ever reaches this point)
3
{
4
    //"This fringe case was reached! Debug this!"
5
    UE_LOG(YourLog,Fatal,TEXT("This fringe case was reached! Debug this!"));
6
}
Copied!
Quick tip print
This a trick for easy print debug, you can use this MACRO at the begin of your cpp
1
#define print(text) if (GEngine) GEngine->AddOnScreenDebugMessage(-1, 1.5, FColor::White,text)
Copied!
then you can use a regular lovely print(); inside to all.
To prevent your screen from being flooded, you can change the first parameter, key, to a positive number. Any message printed with that key will remove any other messages on screen with the same key. This is great for things you want to log frequently.
Other Options for Debugging
Logging message to the screen
For the times when you want to just display the message on the screen, you can also do:
1
 #include <EngineGlobals.h>
2
 #include <Runtime/Engine/Classes/Engine/Engine.h>
3
 // ...
4
 GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, TEXT("This is an on screen message!"));
5
 GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, FString::Printf(TEXT("Some variable values: x: %f, y: %f"), x, y));
Copied!
To prevent your screen from being flooded, you can change the first parameter, key, to a positive number. Any message printed with that key will remove any other messages on screen with the same key. This is great for things you want to log frequently.
Logging message to the ~ Client Console
Pressing the ~ key in Unreal brings up the client console.
If you use the PlayerController class you can print a message to this console, which has the advantage of being a completely different logging space which does not require tabbing out of the game to view easily
1
 PC->ClientMessage("Your Message");
Copied!
​Answerhub post on using ClientMessage:
​Forum Post on post messages to the client console​
Log conventions (in the console, ini files, or environment variables)
[cat] = a category for the command to operate on, or 'global' for all categories.
[level] = verbosity level, one of: none, error, warning, display, log, verbose, all, default
At boot time, compiled in default is overridden by ini files setting, which is overridden by command line
Log console command usage
Log list - list all log categories
Log list [string] - list all log categories containing a substring
Log reset - reset all log categories to their boot-time default
Log [cat] - toggle the display of the category [cat]
Log [cat] off - disable display of the category [cat]
Log [cat] on - resume display of the category [cat]
Log [cat] [level] - set the verbosity level of the category [cat]
Log [cat] break - toggle the debug break on display of the category [cat]
Log command line
-LogCmds=\"[arguments],[arguments]...\" - applies a list of console commands at boot time
-LogCmds=\"foo verbose, bar off\" - turns on the foo category and turns off the bar category
Environment variables
Any command line option can be set via the environment variable UE-CmdLineArgs
set UE-CmdLineArgs=\"-LogCmds=foo verbose breakon, bar off\"
Config file
In DefaultEngine.ini or Engine.ini:
1
[Core.Log]
2
global=[default verbosity for things not listed later]
3
[cat]=[level]
4
foo=verbose break
Copied!
♥ -Rama
Profiling: How to Count CPU Cycles
Macros & Data Types
Last modified 2yr ago