[Unity] 조건부 로깅으로 성능 최적화하기 - CustomLogger 클래스 만들어보기

🧭 개요

Unity 개발하다 보면 Debug.Log를 사용할 일이 많다.
Debug는 생각보다 성능에 영향을 많이 끼치는데, 릴리즈 빌드에 로그가 포함되게 된다면 성능에 영향을 많이 끼치게 된다.
그래서 빌드때마다 코드에 있는 모든 Debug문을 지워주거나 해야 하는데, 해당 작업은 너무 귀찮다...

이번에는 해당 문제를 해결할 수 있도록 조건부 컴파일을 활용한 CustomLogger 클래스를 만들어볼 예정이다.

• ✅ Conditional 속성을 활용한 CustomLogger 클래스 구현하기
• ✅ 빌드 환경에 따라 자동으로 로그 제거하는 시스템 만들기
• ✅ 개발/릴리즈 빌드별 로그 관리 방법 알아보기

🔧 Step 1. CustomLogger 클래스 기본 구조 이해하기

먼저 사용할 핵심 개념을 이해해보자.
일단 Unity에서 Debug.Log는 릴리즈 빌드에서도 호출되어 성능 이슈를 일으킬 수 있기 때문에, 다음과 같은 조건에 맞춰 CustomLogger를 구성하자.

• 핵심 원리: [Conditional("ENABLE_LOG")] 속성을 사용해서 컴파일 시점에 로그 코드를 완전히 제거
• 성능 최적화: 릴리즈 빌드에서는 로그 관련 코드가 아예 존재하지 않음

핵심이 되는 코드는 다음과 같다:

using System.Diagnostics;

public static class CustomLogger
{
    [Conditional("ENABLE_LOG")]
    public static void Log(object message)
    {
        UnityEngine.Debug.Log(message);
    }
}

해당 속성을 사용할 때 주의사항

• 메서드는 반드시 static이어야 함
• 반환형이 void여야 함

⚙️ Step 2. 전체 Debug 메서드 래핑하기

기존 Debug 클래스에서 사용되던 메서드를 Custom Logger에서 매핑해줄 필요가 있다.

1. 기본 로깅 메서드: Log, LogWarning, LogError
2. 포맷 로깅 메서드: LogFormat, LogWarningFormat, LogErrorFormat
3. 예외/어설션 메서드: LogException, LogAssertion, Assert
4. 시각적 디버깅 메서드: DrawLine, DrawRay
5. 유틸리티 메서드: Break, ClearDeveloperConsole

우리는 기본을 Unity Debug API와 동일한 인터페이스로 잡고, 모든 메서드를 래핑할 것이다.

✅ 왜 모든 메서드를 래핑해야 할까?

1. 일관성 보장: 프로젝트 전체에서 동일한 로깅 시스템 사용
2. 쉬운 마이그레이션: 기존 Debug.Log 코드를 쉽게 교체 가능
3. 확장성: 나중에 파일 로깅이나 원격 로깅 기능 추가 시 유리

유니티 Debug Methods는 공식문서에서 확인할 수 있다.

[Debug - Unity 스크립팅 API

Class containing methods to ease debugging while developing a game.

docs.unity3d.com](https://docs.unity3d.com/kr/2021.3/ScriptReference/Debug.html)

적용방법

[Conditional("ENABLE_LOG")]
public static void LogWarning(object message, Object context)
{
    UnityEngine.Debug.LogWarning(message, context);
}

[Conditional("ENABLE_LOG")]
public static void DrawLine(Vector3 start, Vector3 end, Color color = default(Color), float duration = 0.0f, bool depthTest = true)
{
    UnityEngine.Debug.DrawLine(start, end, color == default(Color) ? Color.white : color, duration, depthTest);
}

📄 Step 3. 프로젝트에 적용 및 심볼 정의하기

프로젝트 설정 방법

1. 스크립트 추가: CustomLogger.cs 파일을 프로젝트에 추가
2. 심볼 정의: Player Settings → Other Settings → Scripting Define Symbols에 ENABLE_LOG 추가 (개발용)
3. 기존 코드 교체: Debug.Log → CustomLogger.Log로 변경

Scripting Define Symbols에 ENABLE_LOG 추가

릴리즈 빌드 설정

• 릴리즈용 빌드 설정에서는 ENABLE_LOG 심볼을 제거
• 모든 CustomLogger 호출이 컴파일 시점에 완전히 제거됨

Unity 6 부터는 빌드 창에서 빌드 프로필을 여러개로 구성하는 것을 지원한다.
테스트 빌드 프로필 / 릴리즈 빌드 프로필을 구분하여 사용하면 편리하게 사용할 수 있다.

릴리즈 빌드 설정

이제 테스트를 진행해보자.
씬에서 간단한 스크립트를 만들고, CustomLogger를 사용해보자

using UnityEngine;

public class TestC : MonoBehaviour
{
    private int playerHealth = 100;
    void Start()
    {
        // 기존 코드
        Debug.Log("[Debug]플레이어 HP: " + playerHealth);

        // CustomLogger 사용
        CustomLogger.Log("[CustomLogger]플레이어 HP: " + playerHealth);
    }

  
}

콘솔 창

다음과 같이 잘 적용된 것을 확인할 수 있다!

⚠️주의사항

----Logger 클래스로 정의하고, 메소드는 Log로 시작해야 콘솔 창에서 코드로 바로 접근 가능하다. 

Logging 과 같이 정의하면 콘솔에서 더블 클릭 시 Logging 클래스로 넘어가는 상황이 발생한다. 

**공식 내용은 아니지만, Logging 클래스로 테스트 해봤을 때 해당 현상이 발생하였다. 

https://www.reddit.com/r/Unity3D/comments/17eikh0/i_found_a_way_to_go_to_the_right_line_in_your/

From the Unity3D community on Reddit: I found a way to go to the "right line in your code" when double-clicking a custom log mes

 

✅ 결과 요약

• 개발 환경: ENABLE_LOG 심볼 정의 시 모든 로그가 정상 출력
• 릴리즈 빌드: 심볼 미정의 시 로그 코드가 완전히 제거되어 성능 향상
• 코드 일관성: 기존 Debug API와 동일한 인터페이스로 쉬운 마이그레이션 가능

📌 마무리

여기까지 조건부 컴파일을 활용한 CustomLogger 클래스 구현 방법을 알아보았다.
이 과정을 통해, 개발 시에는 풍부한 로그 정보를 확인하면서도, 릴리즈 빌드에서는 성능 저하 없이 깔끔한 코드를 유지할 수 있게 되었고, Unity 프로젝트 최적화를 위한 기반을 다졌다고 볼 수 있다.

🌱 추가적으로 해볼만한 확장

• CustomLogger를 확장하여 파일 로깅 기능 추가하는 방식으로 디버깅 고도화
• 원격 로깅 시스템 구현으로 실제 사용자 환경에서의 로그 수집
• 로그 레벨별 필터링 시스템으로 더 세밀한 로그 관리
• 로그 출력 포맷 커스터마이징으로 가독성 향상

이 글이, Unity 성능 최적화로 고통받던 개발자들에게 도움이 되길 바라면서,

😘 즐코(즐거운 코딩 되세요)!

📄 CustomLogger.cs 전체 소스코드 보기

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using System.Diagnostics;

public static class CustomLogger
{
    [Conditional("ENABLE_LOG")]
    public static void Log(object message)
    {
        UnityEngine.Debug.Log(message);
    }

    [Conditional("ENABLE_LOG")]
    public static void Log(object message, Object context)
    {
        UnityEngine.Debug.Log(message, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogFormat(string format, params object[] args)
    {
        UnityEngine.Debug.LogFormat(format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogFormat(Object context, string format, params object[] args)
    {
        UnityEngine.Debug.LogFormat(context, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogWarning(object message)
    {
        UnityEngine.Debug.LogWarning(message);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogWarning(object message, Object context)
    {
        UnityEngine.Debug.LogWarning(message, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogWarningFormat(string format, params object[] args)
    {
        UnityEngine.Debug.LogWarningFormat(format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogWarningFormat(Object context, string format, params object[] args)
    {
        UnityEngine.Debug.LogWarningFormat(context, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogError(object message)
    {
        UnityEngine.Debug.LogError(message);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogError(object message, Object context)
    {
        UnityEngine.Debug.LogError(message, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogErrorFormat(string format, params object[] args)
    {
        UnityEngine.Debug.LogErrorFormat(format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogErrorFormat(Object context, string format, params object[] args)
    {
        UnityEngine.Debug.LogErrorFormat(context, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogException(System.Exception exception)
    {
        UnityEngine.Debug.LogException(exception);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogException(System.Exception exception, Object context)
    {
        UnityEngine.Debug.LogException(exception, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogAssertion(object message)
    {
        UnityEngine.Debug.LogAssertion(message);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogAssertion(object message, Object context)
    {
        UnityEngine.Debug.LogAssertion(message, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogAssertionFormat(string format, params object[] args)
    {
        UnityEngine.Debug.LogAssertionFormat(format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void LogAssertionFormat(Object context, string format, params object[] args)
    {
        UnityEngine.Debug.LogAssertionFormat(context, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void Assert(bool condition)
    {
        UnityEngine.Debug.Assert(condition);
    }

    [Conditional("ENABLE_LOG")]
    public static void Assert(bool condition, object message)
    {
        UnityEngine.Debug.Assert(condition, message);
    }

    [Conditional("ENABLE_LOG")]
    public static void Assert(bool condition, object message, Object context)
    {
        UnityEngine.Debug.Assert(condition, message, context);
    }

    [Conditional("ENABLE_LOG")]
    public static void AssertFormat(bool condition, string format, params object[] args)
    {
        UnityEngine.Debug.AssertFormat(condition, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void AssertFormat(bool condition, Object context, string format, params object[] args)
    {
        UnityEngine.Debug.AssertFormat(condition, context, format, args);
    }

    [Conditional("ENABLE_LOG")]
    public static void DrawLine(Vector3 start, Vector3 end, Color color = default(Color), float duration = 0.0f, bool depthTest = true)
    {
        UnityEngine.Debug.DrawLine(start, end, color == default(Color) ? Color.white : color, duration, depthTest);
    }

    [Conditional("ENABLE_LOG")]
    public static void DrawRay(Vector3 start, Vector3 dir, Color color = default(Color), float duration = 0.0f, bool depthTest = true)
    {
        UnityEngine.Debug.DrawRay(start, dir, color == default(Color) ? Color.white : color, duration, depthTest);
    }

    [Conditional("ENABLE_LOG")]
    public static void Break()
    {
        UnityEngine.Debug.Break();
    }

    [Conditional("ENABLE_LOG")]
    public static void ClearDeveloperConsole()
    {
        UnityEngine.Debug.ClearDeveloperConsole();
    }
}