log.Category

log.Category

#Overview

name: log.Category

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of log.Category is to control the inclusion of category information in log output within the Unreal Engine logging system. It determines whether and how the category is displayed for each log entry.

This setting variable is primarily used by the Unreal Engine’s logging subsystem, which is a core part of the engine’s debugging and monitoring capabilities. It’s referenced in the Launch module, specifically in the LaunchEngineLoop.cpp file, which is responsible for initializing and managing the engine’s core systems.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, but can be changed at runtime through console commands or configuration files.

The log.Category variable interacts directly with its associated variable CVarLogCategory, which is an instance of TAutoConsoleVariable<int32>. This associated variable is used to actually store and retrieve the value of the setting.

Developers should be aware that this variable affects the verbosity and format of log output. The possible values are:

When using this variable, developers should consider the following best practices:

  1. Use the appropriate level of category logging based on the current development or debugging needs.
  2. Be aware that changing this value can affect log readability and potentially impact performance if excessive logging is enabled.
  3. Consider the implications on log parsing and analysis tools when changing this setting.

Regarding the associated variable CVarLogCategory: The purpose of CVarLogCategory is to provide a programmatic interface to the log.Category setting within the C++ code. It allows the engine to efficiently access and modify the logging category behavior at runtime.

This associated variable is used directly in the engine’s code to determine whether to include category information in log output. It’s accessed using the GetValueOnGameThread() method, which suggests that it’s primarily intended to be read on the game thread.

The value of CVarLogCategory is used to set GPrintLogCategory, a global variable that likely controls the actual behavior of the logging system with respect to category printing.

Developers should be aware that changes to CVarLogCategory will immediately affect logging behavior across the engine. They should use the provided console variable interface to modify this value rather than attempting to change it directly, to ensure proper synchronization and notification of changes throughout the engine.

Best practices for using CVarLogCategory include:

  1. Access its value using the provided methods (GetValueOnGameThread()) rather than attempting to read or write to it directly.
  2. Consider the threading implications when accessing this variable, as it’s designed to be safely read from the game thread.
  3. Use this variable in conjunction with other logging-related settings to fine-tune the engine’s logging behavior for specific debugging or profiling needs.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:6261

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLogCategory(
	TEXT("log.Category"),
	1,
	TEXT("Defines if the categoy is included in each line in the log file and in what form.\n"
	     "  0 = Do not log category\n"
	     "  2 = Log the category (default)"),
	ECVF_Default);

#Associated Variable and Callsites

This variable is associated with another variable named CVarLogCategory. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:6260

Scope: file

Source code excerpt:



static TAutoConsoleVariable<int32> CVarLogCategory(
	TEXT("log.Category"),
	1,
	TEXT("Defines if the categoy is included in each line in the log file and in what form.\n"
	     "  0 = Do not log category\n"
	     "  2 = Log the category (default)"),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:6291

Scope (from outer to inner):

file
function     static void CVarLogSinkFunction

Source code excerpt:


	{
		int32 LogCategoryValue = CVarLogCategory.GetValueOnGameThread();

		// Note GPrintLogCategory can be used on multiple threads but it should be no issue to change it on the fly
		GPrintLogCategory = LogCategoryValue != 0;
	}
}