Table of Contents

18. Diagnostics

왜 필요한가

런타임 문제(메모리 누수, 프레임 스파이크, 예외 급증)를 사후에 로그로 추적하면 늦다. Diagnostics는 실시간으로 카운터/이벤트를 관찰하고 경고를 낸다.

언제 사용하는가

Editor/Development Build에서 항상 자동 활성화된다. 개발 중 F1(Runtime Inspector), F2(Command Console)로 확인한다.

프로젝트에서 어떤 역할인가

다른 모든 System은 DiagnosticsCounters.Register()로 자가 등록만 하고 Diagnostics를 역참조하지 않는다 (단방향 의존, Rules #15). Diagnostics는 그 카운터를 읽기만 한다.

실제 게임에서는 언제 호출되는가

Editor/Development Build 전 구간에서 지속적으로 동작하며 Release 빌드에서는 #if UNITY_EDITOR || DEVELOPMENT_BUILD로 완전히 제거된다.

코드 예제

// System 내부에서 자가 등록 (예: 신규 System 작성 시)
DiagnosticsCounters.Register("MySystem.ActiveCount", () => _activeCount, warnThreshold: 100);

// 조회는 Tools > Framework > Diagnostics 또는 코드에서
var report = DiagnosticsReport.Generate();

관련 Sample

Samples/Diagnostics/DiagnosticsSample.cs, Editor/Diagnostics/DiagnosticsWorkspaceSample.cs

Best Practice

  • getter는 부수효과 없는 읽기 전용으로 작성한다 (0.5초 주기로 반복 호출됨).
  • 비정상 임계값이 알려진 카운터는 warnThreshold를 명시한다.
  • Dispose() 시점에 반드시 Unregister()한다.

자주 하는 실수

  • System이 Diagnostics를 역참조 (금지, Rules #15)
  • Register 후 Unregister 누락으로 dangling 카운터가 남음
  • Register/Unregister를 #if UNITY_EDITOR || DEVELOPMENT_BUILD 밖에서 호출 (Release 영향)

실습 과제

  1. 임의의 카운터를 하나 등록하고 Diagnostics Workspace에서 값 변화를 관찰한다.
  2. AllocationSpikeDetection/FrameSpikeDetection 리포트를 확인해본다.

이전 문서 / 다음 문서

이전: 17_TimeSystem.md 다음: 19_Integration.md

관련 API

MCP_Index.md Diagnostics 섹션, MCP_Rules.md #15

Edit this page