Skip to content

FoxLogManager & Configuration

Fox Logging은 NeoDEEX 구성 설정을 이용하여 로거들을 생성하고 이를 바탕으로 유연한 로깅 환경을 구성할 수 있습니다. 로깅 구성 설정을 읽어 로거를 생성하고 어플리케이션 요청에 따라 적절한 로거를 반환하는 작업은 FoxLogManager 클래스를 통해 수행됩니다.

Logging Configuration

로깅 구성 설정은 최상위 섹션인 "logging" 섹션으로부터 정의 됩니다. "logging" 섹션이 존재하지 않는 경우, 구성 설정으로부터 생성되는 로거 프로바이더나 로거는 존재하지 않게 되며 전역 필터 수준은 Warning 이 사용됩니다.

"logging" 섹션은 다음과 같은 속성들을 가질 수 있습니다.

  • filter

    전역 필터 수준을 설정합니다. 명시되지 않은 경우 Warning 수준이 사용됩니다.

  • useFallbackLogger

    대체 로거(fallback logger)의 사용 여부를 설정합니다. 명시 되지 않은 경우 true 입니다.

  • useExactLoggerName

    GetLogger 메서드 호출 시 매개변수로 전달된 로거 이름으로 로거를 찾고, 로거가 존재하지 않는 경우 추가적으로 다른 로거를 찾을 지를 설정합니다. 명시되지 않은 경우 false 입니다. 이 속성을 true 로 설정하면 로거 이름 레벨링(logger name leveling) 기능이 작동하지 않으며 useFallbackLogger 설정값을 무시하며 false 로 간주합니다.

다음은 "logging" 섹션을 사용한 간단한 설정 예를 보여줍니다.

1
2
3
4
5
6
7
{
  "logging": {
    "filter": "Information",
    "useFallbackLogger": false,
    "useExactLoggerName": true
  }
}

"logging" 섹션은 "providers"하위 섹션과 "loggers" 하위 섹견을 가질 수 있으며 이들 컬렉션을 통해 로거 프로바이더와 로거들을 생성할 수 있습니다.

providers subsection

"logging:providers" 섹션은 FoxLogManager가 생성하고 등록할 프로바이더들의 목록을 나타냅니다. "logging:providers" 섹션에는 각 로거 프로바이더의 이름과 생성할 로거 프로바이더 설정이 포함됩니다. 이 섹션을 통해 생성될 프로바이더들은

로거 프로바이더 설정은 로거 프로바이거의 타입("providerType" 속성)과 로거 생성에 사용하는 로거 속성 컬렉션("properties" 속성)을 명시할 수 있습니다. 각 로거 프로바이더 설정은 반드시 "providerType" 속성을 명시해야 하며 "properties" 속성은 옵션입니다.

다음 구성 설정은 3개의 로거 프로바이더를 생성하고 등록하며 각각의 이름은 MyLoggerProvider1, MyLogerProvider2, MyLoggerProvider3 입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "logging": {
    "providers": {
      "MyLoggerProvider1": {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxConsoleLoggerProvider"
      },
      "MyLoggerProvider2": {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxDebugLoggerProvider"
      },
      "MyLoggerProvider3": {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxTextFileLoggerProvider",
        "properties": {
          "filePrefix": "MyLog",
          "directory": "~/Logs"
        }
      }
    }
  }
}

MyLoggerProvider1 프로바이더는 콘솔 로거를 생성하는 FoxConsoleLoggerProvider 타입이이며 MyLoggerProvider2 프로바이더는 디버그 로거를 생성하는 FoxDebugLoggerProvider 타입 입니다. 이들 두 로거 프로바이더는 로거를 생성할 때 추가적인 정보가 필요 없기 때문에 "properties" 속성이 명시되지 않았습니다.

파일 로거를 생성하는 FoxTextFileLoggerProvider 타입은 로그 파일의 이름에 사용할에 접두사 속성("filePrefix" 속성), 로그 파일이 위치할 디렉터리 속성("directory" 속성)을 나열하고 있습니다. 이제, MyLoggerProvider3 프로바이더를 사용하여 로거를 생성하면 ~/Logs 디렉터리에 MyLog로 시작하는 로그 파일을 생성하고 로그를 기록하는 파일 로거를 생성하게 됩니다.

1
2
3
4
5
    "loggers": {
      "MyFileLogger" : {
        "providerName": "MyLoggerProvider3"
      }
    }

"properties" 컬렉션 내에 나타날 수 있는 속성들은 로거 프로바이더 마다 다릅니다. 즉, FoxTextFileLoggerProvider 타입이 사용하는 속성들 목록과 FoxDbLoggerProvider 타입이 사용하는 속성 목록은 완전히 다르기 때문에 각 로거 프로바이더에 관련된 문서를 참고 하십시요.

loggers subsection

"logging:loggers" 섹션은 로거 프로바이더를 통해 생성할 로거들의 목록을 나타냅니다. 이 섹션에 로거 이름과 로거 생성에 사용할 프로바이더를 "providerName" 속성으로 명시하면 FoxLogManager는 이 정보를 사용하여 로거들을 생성합니다. 추가적으로 로거가 사용할 필터 수준을 "filter" 속성에 표시할 수 있습니다.

다음 구성 설정에서 MyLogger라는 이름을 가진 로거는 MyLoggerProvider1 이 생성하는 콘솔 로거로 생성되며 YourLogger는 MyLoggerProvider3가 생성하는 텍스트 파일 로거로 생성됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "logging": {

    ... 앞서 언급된 provider 설정 (생략) ...

    "loggers": {
      "MyLogger" : {
        "providerName": "MyLoggerProvider1",
        "filter": "Information"
      },
      "YourLogger" : {
        "providerName": "MyLoggerProvider3",
        "filter": "Warning"
      }
    }
  }
}

"logging:loggers" 섹션에서 나열되는 로거는 로거 프로바이더 이름 대신 로거 프로바이더 타입을 곧바로 명시할 수 있습니다. 이 경우, FoxLogManager는 "logging:providers" 설정이 없어더라도 주어진 타입을 사용하여 로거 프로바이더를 생성하고 로거 프로바이더의 CreateLogger 메서드를 호출하여 로거를 생성합니다. 로거 프로바이더 타입은 providerType 속성을 통해 명시할 수 있습니다.

로거 프로바이더 이름을 사용하는 위 구성 설정은 로거 프로바이더 타입을 사용하는 다음 구성 설정과 동일하게 작동합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "logging": {
    "loggers": {
      "MyLogger" : {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxConsoleLoggerProvider",
        "filter": "Information"
      },
      "YourLogger" : {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxTextFileLoggerProvider",
        "properties": {
          "filePrefix": "MyLog",
          "directory": "~/Logs"
        },
        "filter": "Warning"
      }
    }
  }
}

로거 프로바이더 이름을 사용하거나 로거 프로바이더 타입을 사용할 때 로거 생성 속성을 명시할 수 있습니다. 로거 프로바이더 이름을 사용할 때, "logging:loggers" 섹션에서 사용된 로거 생성 속성은 "logging:providers" 섹션에서 사용된 로거 생성 속성을 오버라이드(override) 합니다. 예들 들어 다음과 같은 구성 설정에서 MyLogger 설정은 현재 디렉터리의 하위 Logs 폴더에 로그를 생성하는 반면 YourLogger 설정은 C:\Logs 폴더에 로그 파일을 생성합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "logging": {
    "providers": {
      "MyLoggerProvider3": {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxTextFileLoggerProvider",
        "properties": {
          "filePrefix": "MyLog",
          "directory": "~/Logs"
        }
      }
    },
    "loggers": {
      "MyLogger" : {
        "providerName": "MyLoggerProvider3"
      },
      "YourLogger" : {
        "providerName": "MyLoggerProvider3",
        "properties": {
          "directory": "C:\\Logs"
        }
      }
    }
  }
}

FoxLogManager

FoxLogManager 클래스는 Fox Logging 구성 설정을 읽고 로거와 로거 프로바이더를 생성하고 등록하여 관리하는 핵심 클래스 입니다.

Global settings

FoxLogManager 클래스는 전역 로그 필터와 같은 전역 설정들을 구성 설정에서 읽어 속성으로 접근 가능하게 합니다.

  • GlobalFilterLevel 속성

    전역 필터 레벨을 읽거나 설정합니다. 로깅 구성 설정에 전역 필터 수준("logging:filter" 속성)이 존재하는 경우, 이 속성을 통해 구성 설정 값을 읽을 수 있습니다. 이 속성 값을 변경한 경우, 구성 설정의 값을 덮어 씁니다.

    Warning

    구성 설정을 통해 로거를 생성하기 전에 이 속성 값을 변경해야만 변경된 전역 필터 수준이 로거에 적용됩니다. 구성 설정을 읽어 로거를 생성하는 시점은 Providers 속성, Loggers 속성, GetLoggerProvider, GetLogger 메서드가 최초로 호출되는 시점입니다.

  • UseFallbackLogger 속성

    대체 로거 사용 여부를 설정합니다. 로깅 구성 설정에 대체 로거 사용 여부("loggging:useFallbackLogger" 속성)가 존재하는 경우, 이 속성을 통해 구성 설정값을 읽을 수 있습니다. 이 속성 값을 변경하면 구성 설정의 값을 덮어 씁니다.

    UseFallbackLogger 속성은 UseExactLoggerName 속성이 값이 false 일 때만 효과가 있습니다. 즉, UseExactLoggerName 속성이 true 인 경우, UseFallbackLogger 속성 값은 무시되어 항상 false 로 간주합니다. 상세한 내용은 진단 기능 문서를 참고 하십시요.

  • UseExactLoggerName 속성

    로거 이름 레벨링의 사용 여부를 설정합니다. 이 속성 값이 true 로 지정되면 로거 이름 레벨링은 사용되지 않습니다. 로깅 구성 설정에 대체 로거 사용 여부("loggging:useExactLoggerName" 속성)가 존재하는 경우, 이 속성을 통해 구성 설정값을 읽을 수 있습니다. 이 속성 값을 변경하면 구성 설정의 값을 덮어 씁니다.

FoxLogManager 클래스는 구성 설정의 "logging:providers" 섹션을 읽어 로거 프로바이더들을 생성하고 관리합니다. 또한 RegisterProvider 메서드 및 UnregisterProvider 메서드를 통해 로거 프로바이더의 등록 및 등록 해제를 수행할 수도 있습니다.

  • Providers 속성

    등록된 로거 프로바이더에 대한 컬렉션(IEnumerable<IFoxLoggerProvider>)을 반환합니다.

  • RegisterProvider/UnregisterProvider 메서드

    로거 프로바이더를 코드를 통해 등록하거나 등록해제 할 수 있도록 제동되는 메서드들 입니다. 구성 설정 파일을 사용하기 어렵거나 구성 설정 파일 이외에 추가적인 로거 프로바이더를 등록하고자 할 때 사용할 수 있습니다.

    IFoxLogProvider provider = new MyLoggerProvider("providerName", FoxLoggerPropertyCollection.Empty);
FoxLogManager.RegisterProvider(provider);

  • GetLoggerProvider 메서드

    등록된 로거 프로바이더들 중에서 주어진 이름을 갖는 로거 프로바이더를 찾아 반환합니다. 로거 프로바이더의 이름은 레벨링 기능응 지원하지 않습니다. 즉,매개변수로 주어진 이름의 로거 프로바이더를 찾고 존재하지 않는 경우 null 값을 반환합니다.

FoxLogManager 클래스는 구성 설정의 "logging:loggers" 섹션을 읽어 로거를 생성하고 관리합니다. 구성 설정을 사용하지 않더라도 RegistgerLogger 메서드 및 UnregisgerLogger 메서드를 사용하여 로거를 등록하거나 기존에 등록된 로거를 등록 해제할 수 있습니다. 이 외에도 SafeLogger, FallbackLogger 속성등을 통해 추가적인 기능들을 제공합니다.

  • Loggers 속성

    등록된 로거들에 대한 컬렉션(IEnumerable<IFoxLogger>)을 반환합니다. 이 속성을 통해 특정 로거를 찾는 방법은 권장하지 않습니다. 이 컬렉션을 통해 로거를 찾는 방법은 Fox Logging이 제공하는 대체 로거나 로거 이름 레벨링 기능이 제공되지 않기 때문입니다.

  • RegisterLogger/UnRegisterLogger 메서드

    로깅 구성 설정과 관계 없이 로거를 등록하거나 등록해제 하는 메서드 입니다. 구성 설정 파일을 사용하기 어렵거나 구성 설정 파일 이외에 추가적인 로거 프로바이더를 등록하고자 할 때 사용할 수 있습니다.

    FoxTextFileLogger logger = new("MyNewLogger", "MyLogFile", "~/Logs");
FoxLogManager.RegisterLogger(logger);

  • GetLogger 메서드

    GetLogger 메서드는 FoxLogManager 에 등록된 로거들 중 로거 이름을 사용하여 로거를 획득하는데 사용됩니다. GetLogger 메서드는 찾고자 하는 로거 이름을 명시하기위해 문자열, Type, 제너릭 매개변수를 사용하는 3가지 오버로드 메서드를 제공합니다. 다음 3 메서드 호출은 동등한 GetLogger 메서드 호출입니다.

    IFoxLog log1 = FoxLogManager.GetLogger(typeof(MyClass).FullName);
IFoxLog log2 = FoxLogManager.GetLogger(typeof(MyClass));
IFoxLog log3 = FoxLogManager.GetLogger<MyClass>();

    GetLogger 메서드는 주어진 이름을 가진 로거가 존재하지 않더라도 null 을 반환하지 않습니다. GetLogger 메서드는 로거 이름 레벨링을 통해 로거를 찾으려고 시도하고 로거를 찾지 못한 경우 대체 로거를 반환합니다.

    Tip

    GetLogger 메서드의 이러한 작동 방식은 UseFallbackLogger 및 UseExactLoggerName 속성을 통해 제어할 수 있습니다. 상세한 내용은 진단 기능 문서를 참고하십시요.

  • FindLogger 메서드

    Note

    대부분의 상황에서 어플리케이션은 GetLogger 메서드를 호출하는 것이 좋습니다. FindLogger 메서드는 문제 해결을 위한 코드에서만 사용하십시요.

    GetLogger 메서드는 null 을 반환하지 않는 반면 FindLogger 메서드는 null 을 반환할 수 있습니다. UseFallbackLogger 및 UseExactLoggerName 속성 값의 설정에 따라 대체 로거를 반환하지 않고 null 을 반환할 수도 있습니다. 예를 들어 UseFallbackLogger 속성이 false 이고 UseExactLoggerName 속성이 true 인 경우, FoxLogerManager 는 주어진 이름의 로거를 찾을 수 없는 경우 null 을 반환합니다. 동일한 상황에서 GetLogger 메서드는 로거를 찾을 수 없다는 메시지와 함께 FoxInvalidConfigurationException 예외를 발생시킵니다.

  • SafeLogger 속성

    SafeLogger 속성은 오류 발생 가능성이 가장 낮으면서 추후에 로그를 살펴볼 수 있도록 제공되는 빌트 인 로거 입니다. 실제로 SafeLogger 속성은 FoxTextFileLogger 객체를 통해 구현된 IFoxLog 인터페이스를 반환하며 로그 파일은 %TEMP% 폴더의 하위에 FoxLog 라는 디렉터리에 생성됩니다. 로그 파일 이름은 NeoDEEX_yyyyMMdd.log 형태로서 1주일마다 월요일 날짜로 새로운 파일이 생성됩니다.

    NeoDEEX 프레임워크 내부에서는 로그를 기록하기 어려운 상황이거나 로거 내부에서 발생하는 오류를 기록하기 위해 SafeLogger 를 사용합니다. 어플리케이션 코드에서도 비슷한 상황에서 SafeLogger 속성을 사용하여 로그를 남길 수 있습니다.

    Warning

    SafeLogger 를 로그를 남기는 주요 로거로 사용하지 마십시요. NeoDEEX 를 사용하는 모든 프로세스들이 SafeLogger 속성에 의해 로그를 기록하기 때문에 하나의 파일이 여러 프로세스에 의해 공유되므로 상당한 부하를 가질 수 있습니다.

  • FallbackLogger 속성

    GetLogger 혹은 FindLogger 메서드가 반환하는 대체 로거는 싱글톤 인스턴스 로거입니다. 이 싱글톤 로거를 FallbackLogger 속성을 통해 접근할 수 있습니다. GetLogger 메서드가 반환하는 로거가 대체 로거인가를 확인하기 위해 두 값을 비교할 수도 있습니다.

    1
2
3
4
5
    IFoxLog log = FoxLogManager.GetLogger("SomeLoggerName");
if (Object.ReferenceEqual(log, FoxLogManager.FallbackLogger))
{
    // 대체 로거
}

Other methods

FoxLogManager 클래스는 로거 프로바이더, 로거와 관련된 메서드들 외에도 다음과 같은 메서드들을 제공합니다.

  • GetLogDateTime 메서드

    GetLogDateTime 메서드는 로그에 기록할 로그 발생 시간을 표준 문자열 포맷팅을 사용하여 문자열로 반환합니다. 로그 발생 시간은 GetLogTimestamp 메서드를 사용하며 이 메서드는 설정에 따라 UTC 시간 혹은 로컬 시간으로 현재 시간을 반환하며 표준 날짜 포맷팅은 DefaultDateTimeFormat 속성을 사용합니다.

    Console.WriteLine($"GetLogDateTime() = {FoxLogManager.GetLogDateTime()}");
// 출력: GetLogDateTime() = 2021-12-20 14:39:17.00535

  • GetLogLevelChar 메서드

    콘솔 로거나 디버그 로거, 텍스트 파일 로거와 같이 텍스트를 기록하는 로그는 로그 메시지의 로그 수준을 맨 앞에 한 글자로 표시합니다. Critical 수준은 C, Error 수준은 E, Warning 수준은 W 문자가 표시되는 방식 입니다. GetLogLevelChar 메서드는 로그 수준에 대한 문자를 반환합니다. 로거는 이 메서드를 사용하여 로그 메시지의 로그 수준을 표시하게 됩니다.

  • GetFormattedString 메서드

    텍스트를 기록하는 로거는 GetFormattedString 메서드를 호출하여 표준적인 로그 메시지 포맷팅을 사용하여 로그 메시지를 표시할 수 있습니다. 실제로 NeoDEEX가 제공하는 FoxConsoleLogger, FoxDebugLogger, FoxTextFileLogger 클래스는 이 메서드를 호출하여 로그 메시지를 구하고 이를 각각 콘솔, 디버거, 파일에 기록합니다.

    Console.WriteLine(FoxLogManager.GetFormattedString("MySource", FoxLogLevel.Warning, "Log message..."));
// 출력: W 2022-04-13 15:43:17.86102 [MySource] Log message...