4-1. GC 통계 명령어 | UE5 GC Deep Dive

SECTION 01

stat gc - GC 실시간 통계

가비지 컬렉션 성능을 실시간으로 모니터링하는 핵심 명령어

stat gc 사용법

                    콘솔
                    // 실시간 GC 통계 표시 토글
stat gc

// 출력 항목 설명:
Num GC cycles:           150    ← 총 GC 사이클 수
Total GC time:          45.2 ms ← 누적 GC 시간
Average GC time:         2.1 ms ← 평균 GC 시간
Max GC time:            12.5 ms ← 최대 GC 시간 (히치 원인)
Objects Destroyed:      1523    ← 파괴된 UObject 수
UObject Count:        85234     ← 현재 활성 UObject 수
GC Clusters:           4521     ← 활성 클러스터 수
                

stat gc 읽는 법

가장 중요한 지표는 Max GC time입니다. 이 값이 프레임 예산(60fps=16.6ms)의 20%를 초과하면 GC 최적화가 필요합니다. 목표: Max GC time < 3ms (60fps), < 5ms (30fps).

SECTION 02

obj 명령어 시리즈

UObject 관련 디버깅 명령어의 완전 가이드

obj gc - 강제 GC 실행

                    콘솔
                    // 강제 가비지 컬렉션 실행
obj gc

// 특정 조건으로 GC 실행
gc.CollectGarbageEveryFrame 1    // 매 프레임 GC (디버깅용)
gc.CollectGarbageEveryFrame 0    // 복원
                

obj list - 객체 목록 조회

                    콘솔
                    // 모든 클래스별 UObject 수
obj list

// 특정 클래스만
obj list class=StaticMeshComponent
obj list class=SkeletalMeshComponent
obj list class=Actor

// 외부 패키지 객체
obj list class=Package

// 출력 예시:
Class                    Count   NumKB   MaxKB
StaticMeshComponent      3521    45200   128
SkeletalMeshComponent     156    23400   512
Actor                    1205     8400    32
                

obj refs - 참조 관계 조회

                    콘솔
                    // 특정 객체의 참조 관계
obj refs name=MyActor_42

// 출력: 이 객체를 참조하는 모든 객체 목록
Referencers of MyActor_42:
  UWorld /Game/Maps/MainMap.MainMap (Property: Actors)
  UMyManager_0 (Property: TrackedActors)
  UGameInstance_0 (FGCObject reference)
                

SECTION 03

GC 콘솔 변수 (gc.*)

런타임에서 GC 동작을 조정하는 변수들

핵심 gc.* 변수

변수	기본값	설명
`gc.TimeLimitSeconds`	0.002	프레임당 GC 시간 제한
`gc.TimeBetweenPurgingPendingKillObjects`	60.0	자동 GC 실행 간격(초)
`gc.MaxObjectsInGame`	2162688	게임에서 최대 UObject 수
`gc.MaxObjectsInEditor`	12582912	에디터에서 최대 UObject 수
`gc.MaxObjectsNotConsideredByGC`	0	DisregardForGC 풀 크기
`gc.NumRetriesBeforeForcingGC`	10	강제 GC 전 재시도 횟수
`gc.AllowIncrementalReachability`	1	Incremental GC 활성화
`gc.CreateGCClusters`	1	Cluster GC 활성화
`gc.MinGCClusterSize`	5	최소 클러스터 멤버 수

                    콘솔
                    // 현재 값 확인
gc.TimeLimitSeconds
// 출력: gc.TimeLimitSeconds = 0.002000

// 값 변경
gc.TimeLimitSeconds 0.005

// 디버깅: 매 프레임 GC + Full GC
gc.CollectGarbageEveryFrame 1
gc.AllowIncrementalReachability 0
                

SECTION 04

실전 디버깅 워크플로

GC 문제를 단계적으로 진단하는 실전 방법론

GC 문제 진단 순서

                    진단 워크플로
                    // Step 1: GC 시간 확인
stat gc
// → Max GC time > 5ms? → 최적화 필요

// Step 2: UObject 수 확인
obj list
// → 예상보다 많은 클래스가 있는지 확인

// Step 3: 의심 클래스 상세 조회
obj list class=MyProjectile
// → 수천 개의 Projectile? → 풀링 필요

// Step 4: 누수 의심 객체 참조 확인
obj refs name=MyProjectile_2500
// → 누가 이 객체를 참조하고 있는지 확인

// Step 5: 강제 GC로 수거 확인
obj gc
obj list class=MyProjectile
// → GC 후에도 줄지 않으면 → 참조 누수 확정

// Step 6: 프로그래밍적 확인
// C++ 코드에서:
UE_LOG(LogGC, Warning, TEXT("Objects: %d"),
    GUObjectArray.GetObjectArrayNum());
                

로그 기반 GC 모니터링

-LogGC 커맨드 라인 옵션이나 LogGarbage 카테고리를 활성화하면 매 GC 사이클의 상세 로그를 확인할 수 있습니다. 프로덕션에서는 성능 영향이 있으므로 디버그 빌드에서만 사용하세요.

SUMMARY

핵심 요약

이 강의에서 배운 내용

stat gc는 GC 시간, 객체 수, 클러스터 수 등 실시간 GC 통계를 표시합니다
obj list/refs/gc로 UObject 현황 조회, 참조 추적, 강제 GC가 가능합니다
gc.* 콘솔 변수로 런타임에서 GC 타이밍, 모드, 제한을 조정할 수 있습니다
GC 문제 진단은 stat gc → obj list → obj refs → obj gc 순서로 진행합니다
Max GC time 목표: 60fps에서 3ms 이하, 30fps에서 5ms 이하입니다

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: stat gc 명령어 분석

에디터에서 stat gc를 활성화하고, 레벨에 Actor 100개를 스폰/디스폰하면서 표시되는 각 수치(Mark Time, Sweep Time, Destroy Time, Objects Destroyed 등)의 변화를 기록하세요. 각 수치의 의미를 정리한 표를 작성하세요.

실습 2: obj list를 활용한 객체 통계 수집

obj list class=StaticMeshComponent, obj list class=Actor, obj list -gc 등의 명령어를 실행하여 현재 월드의 객체 분포를 분석하세요. 가장 많은 메모리를 차지하는 객체 클래스 Top 10을 정리하세요.

심화 과제: 자동화된 GC 메트릭 수집 시스템

FCoreDelegates::GetGarbageCollectDelegate()에 바인딩하여 매 GC 사이클의 소요 시간, 수집된 객체 수, 현재 UObject 총 수를 CSV 파일에 자동 기록하는 프로파일링 시스템을 구현하세요.