UE_C++ —— Logging in Unreal

UE_LOG-toc" name="tableOfContents" style="margin-left:80px">一，UE_LOG

Log Verbosity

Console Commands

Logging Fundamental Data Types

Define Your Own Log Category

UE_LOGFMT-toc" name="tableOfContents" style="margin-left:80px">二，UE_LOGFMT

On-screen debug messages

日志是一种非常实用的调试工具，可以详细说明代码当前的执行逻辑；可以检查函数之间传递的数据值，并报告潜在的问题；

引擎中的日志提供了多种方法，来有序记录运行时特定时刻的事件、函数调用和变量值；
在 Window > Output Log 查看编辑器中的日志；
日志保存在项目 Saved/Logs 目录的 .txt 文件中；

UE_LOG" name="%E4%B8%80%EF%BC%8CUE_LOG" style="background-color:transparent">一，UE_LOG

UE_LOG 是一个将格式化消息记录到日志文件中的宏；

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

第一个输入参数 LogTemp 是提供给 DEFINE_LOG_CATEGORY 宏的类别名称；可在位于 CoreGlobals.h 的引擎中找到这些类别；可自行创建自定义日志记录类别；
第二个输入参数 Warning 是一个日志详细级别，用于将警告打印到控制台和日志文件中；可设置不同的日志详细程度，调整日志的换行模式，或者设置日志的文本颜色；
第三个输入参数 Text 是C语言库函数printf样式中字符串文字的格式；

Log Verbosity

ELogVerbosity 是一个定义日志记录系统日志详细级别的枚举；它定义了额外的非日志详细级别，允许给定日志换行或设置日志文本的颜色；

Enum	Description
Fatal	始终将致命错误打印到控制台和日志文件，然后出现崩溃（即使禁用日志）；
Error	将错误打印到控制台和日志文件；Commandlet和编辑器会收集并报告错误；错误消息导致commandlet故障；
Warning	将警告打印到控制台和日志文件；Commandlet和编辑器会收集并报告警告；
Display	将消息打印到控制台和日志文件；
Log	将消息打印到日志文件，但不打印到控制台；
Verbose	如为给定类别启用了冗长日志记录，则将冗长消息打印到日志文件；这通常用于详细日志记录；
VeryVerbose	将冗长消息打印到日志文件；如启用了极其冗长日志记录，则这将用于详细日志记录，否则将产生垃圾信息输出；

Console Commands

使用 -LogCmds= 时，可以从命令行更改不同日志类别的冗长度；

-LogCmds="LogDerivedDataCache Verbose"

可以使用此命令指定多个类别，包括可将每个日志类别切换到特定日志详细级别的"全部"类别；

Logging Fundamental Data Types

Data Type	Example
Fstring	`UE_LOG(LogTemp, Warning, TEXT("An Actor's name is %s"), *ExampleActor->GetName());`
Bool	`UE_LOG(LogTemp, Warning, TEXT("The boolean value is %s"), ( bExampleBool ? TEXT("true"): TEXT("false") ));`
Integer	`UE_LOG(LogTemp, Warning, TEXT("The integer value is: %d"), ExampleInteger);`
Float	`UE_LOG(LogTemp, Warning, TEXT("The float value is: %f"), ExampleFloat);`
FVector	`UE_LOG(LogTemp, Warning, TEXT("The vector value is: %s"), *ExampleVector.ToString());`
Multiple Specifiers	`UE_LOG(LogTemp, Warning, TEXT("Current values are: vector %s, float %f, and integer %d"), *ExampleVector.ToString(), ExampleFloat, ExampleInteger);`

Define Your Own Log Category

可自行定义日志类别，并将其用在C++代码示例中；如示例有多个文件或框架需要进行不同的分类，此功能可能会很有用；

在相关的头文件中，在include指令下方添加以下内容：

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

其中 <LOG_CATEGORY> 是自定义日志类别字符串，和以下表格值之一：

Log verbosity levels
Verbosity Level	Printed in Console	Printed in Editor Log	Text Color	Additional Information
Fatal	Y	NA	NA	会话崩溃；
Error	Y	Y	Red	NA
Warning	Y	Y	Yellow	NA
Display	Y	Y	Grey	NA
Log	N	Y	Grey	NA
Verbose	N	N	NA	NA
VeryVerbose	N	N	NA	可使用日志掩码和特殊枚举值设置文本颜色；

在相关的C++文件中，在include指令下方添加以下内容：

DEFINE_LOG_CATEGORY(<LOG_CATEGORY>);

注，可以继承 FOutputDevice，以实现自己的输出；

UE_LOGFMT" name="%E4%BA%8C%EF%BC%8CUE_LOGFMT">二，UE_LOGFMT

UE_LOGFMT 会记录结构化日志事件，支持 Positional 或 Named 参数，但不能混合使用两种类型；要使用此宏，需要包含 Logging/StructeredLog.h 库声明；

注，UE5.2中引入了 UE_LOGFMT 宏，检查当前的引擎是否为最新版本；

Parameter Name Description

Positional

字段值必须与格式引用的字段完全匹配；

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

Named

字段值必须包含格式引用的每个字段；顺序无关紧要，而且允许使用额外字段；

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

字段名称必须匹配"[A-Za-z0-9_]+"格式，并且在此日志事件中必须唯一；字段值使用SerializeForLog或运算符 <<(FCbWriter&, FieldType) 进行序列化；

CategoryName ：DECLARE_LOG_CATEGORY_* 声明的日志类别的名称；
Verbosity ：ELogVerbosity 中的日志详细级别的名称；
Format ：以 FLogTemplate 样式格式化字符串；
Fields[0-16] ： 0到16字段或字段值；

On-screen debug messages

屏幕调试消息也能起到很好的信息传递作用，可使用以下代码添加屏幕调试消息：

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

第一个输入参数 key 会获取一个唯一的整型值，用于防止同一消息被多次添加；
第二个输入参数 TimeToDisplay 会获取一个浮点值，用于表示消息在显示多少秒后消失；
第三个输入参数 DisplayColor 用于指定文本显示的颜色；
第四个输入参数 DebugMessage 是要显示的消息；可以像使用日志那样，在屏幕调试消息中使用格式说明符和变量；