Unreal NetWork 00. 커스텀 로그 (Custom Log)

kim-link 2025. 3. 17. 23:52

개요

언리얼 엔진에서 제공하는 강력한 디버깅 도구인 로그 매크로 코드를 살펴보고, 커스텀 로그를 설정하는 방법을 알아보자

LogMacros.h

/** 
 * A macro to declare a logging category as a C++ "extern", usually declared in the header and paired with DEFINE_LOG_CATEGORY in the source. Accessible by all files that include the header.
 * @param CategoryName, category to declare
 * @param DefaultVerbosity, default run time verbosity
 * @param CompileTimeVerbosity, maximum verbosity to compile into the code
 **/
#define DECLARE_LOG_CATEGORY_EXTERN(CategoryName, DefaultVerbosity, CompileTimeVerbosity) \
	extern struct FLogCategory##CategoryName : public FLogCategory<ELogVerbosity::DefaultVerbosity, ELogVerbosity::CompileTimeVerbosity> \
	{ \
		FORCEINLINE FLogCategory##CategoryName() : FLogCategory(TEXT(#CategoryName)) {} \
	} CategoryName;

/** 
 * A macro to define a logging category, usually paired with DECLARE_LOG_CATEGORY_EXTERN from the header.
 * @param CategoryName, category to define
**/
#define DEFINE_LOG_CATEGORY(CategoryName) FLogCategory##CategoryName CategoryName;



/** 
 * A  macro that outputs a formatted message to log if a given logging category is active at a given verbosity level
 * @param CategoryName name of the logging category
 * @param Verbosity, verbosity level to test against
 * @param Format, format text
 ***/
#define UE_LOG(CategoryName, Verbosity, Format, ...) \
{ \
	CA_CONSTANT_IF((ELogVerbosity::Verbosity & ELogVerbosity::VerbosityMask) <= ELogVerbosity::COMPILED_IN_MINIMUM_VERBOSITY && (ELogVerbosity::Warning & ELogVerbosity::VerbosityMask) <= FLogCategory##CategoryName::CompileTimeVerbosity) \
	{ \
		UE_INTERNAL_LOG_IMPL(CategoryName, Verbosity, Format, ##__VA_ARGS__); \
	} \
}

언리얼의 오픈 소스코드에서 매크로 설정을 어떻게 하는지 설명을 읽어보고 설정하려고 한다

개념 학습

언리얼 매크로를 통해 Custom Log 를 만드는 과정에 대해서 학습한다.

CustomLog 선언하기

DECLARE_LOG_CATEGORY_EXTERN(LogABNetwork, Log, All);

선언하는 방법은 DECLARE_LOG_CATEGORY_EXTERN(CategoryName, DefaultVerbosity, CompileTimeVerbosity) 을 사용한다

Category : 카테고리 이름을 설정한다
DefaultVerbosity : 로그 출력, 표시를 어떻게 할 지 설정한다
CompileTimeVerbosity : 최종 빌드에 포함할 로그 수준을 결정한다

LogABNetwork 라는 로그는 Log 라는 채널로 표시를 할 것이고, 최종 빌드에 포함해서 출력하겠다는 뜻이다.

CustomLog 정의하기

DEFINE_LOG_CATEGORY(LogABNetwork);

정의하는 방법은 DEFINE_LOG_CATEGORY(CategoryName) 을 사용한다
CategoryName : 앞서 선언했던 Category 의 이름을 넣어주면 해당 로그를 사용할 수 있게 된다

LogABNetwork 라는 로그를 사용하겠다는 뜻이다.

CustomLog 사용하기

UE_LOG(Category, Verbosity, TEXT(Format), ##__VA_ARGS__);

사용하는 방법은 UE_LOG(CategoryName, Verbosity, Format, ...) 을 사용한다

CategoryName : 내가 사용할 카테고리의 이름이다
Verbosity : 사용할 카테고리의 표시 방법을 설정한다
Format : 어떤 포맷으로 사용할지를 정한다
.... : 가변 인자로 포맷 지정자에 대응하는 추가 인자들을 입력한다

CustomLog 재정의하기

#define AB_LOG(LogCat, Verbosity, Format, ...) UE_LOG(LogCat, Verbosity, TEXT("%s"), *FString::Printf(Format, ##__VA_ARGS__))

사용성이 좋게 만들기 위해 define 을 사용하여 재정의한다

AB_LOG(LogABNetwork, Log, TEXT("%s"), TEXT("Begin")); 이런 식으로 사용하면 된다.

Log 를 만들 때 Format 이하 부분에서 랩핑을 잘못할 경우 크래쉬를 유발하여 에디터가 다운될 수 있다.

실수로 문자열 포맷 지정자와 포맷 인자의 개수가 매칭되지 않아 에러가 발생했다

잘못 사용한 예시

#define AB_LOG(LogCat, Verbosity, Format, ...) UE_LOG(LogCat, Verbosity, TEXT("[%s][%s/%s] %s %s"), *FString::Printf(Format, ##__VA_ARGS__))

부모 클래스의 함수를 override 하고 Super 전후로 로그를 넣어 함수 실행 순서를 알 수 있다

실습해 보기

커스텀로그 설정하기

로그용 클래스 .h 에 추가할 내용

#define AB_LOG(LogCat, Verbosity, Format, ...) UE_LOG(LogCat, Verbosity, TEXT("%s"), *FString::Printf(Format, ##__VA_ARGS__))
DECLARE_LOG_CATEGORY_EXTERN(LogABNetwork, Log, All);

로그용 클래스 .cpp 에 추가할 내용

DEFINE_LOG_CATEGORY(LogABNetwork);

로그를 출력할 클래스 .cpp 함수에 추가할 내용

void AABPlayerController::BeginPlay()
{
	AB_LOG(LogABNetwork, Log, TEXT("%s"), TEXT("Begin"));

	Super::BeginPlay();

	AB_LOG(LogABNetwork, Log, TEXT("%s"), TEXT("End"));
}

로그가 단 하나뿐이라 괜찮지만, 로그가 많아질 경우 어떤 함수가 호출된 건지 알 수 있도록 로그 매크로를 업그레이드해 보자

Actor 및 Function 확인 기능 업데이트

#define LOG_CALLINFO ANSI_TO_TCHAR(__FUNCTION__)
#define AB_LOG(LogCat, Verbosity, Format, ...) UE_LOG(LogCat, Verbosity, TEXT("%s %s"), LOG_CALLINFO, *FString::Printf(Format, ##__VA_ARGS__))

ANSI_TO_TCHAR 매크로를 통해 ANSI 문자열을 WCHAR 문자열로 변환해 주고
__FUNCTION__ 는 컴파일러가 자동으로 제공하는 내장 매크로로 현재 함수의 이름을 문자열 상수로 반환해 준다.
이를 조합하여 현재 함수 이름을 TCHAR 문자열로 반환 후 이를 포맷 지정자로 넘겨주면 로그로 볼 수 있게 된다.

변경 후 모습

필요에 따라 로그를 커스텀할 수 있다면 디버깅 능력 향상에 큰 도움이 될 것 같다