Skip to content

FoxTextFileLogger

FoxTextFileLogger 는 텍스트 파일에 로그를 기록하는 로그로서 NeoDEEX 로깅 환경에서 가장 많이 사용되는 로거 입니다. 관련된 예제 코드는 텍스트 파일 로거 예제를 참조 하십시요.

Major Features

FoxTextFileLogger 는 여러 가지 강력한 기능을 제공하며 성능 또한 매우 우수하기 때문에 어플리케이션의 메인 로거로서 사용이 가능합니다.

  • 다양한 로그 파일 생성 옵션

    FoxTextFileLogger 가 생성하는 로그 파일은 다양한 방식을 취할 수 있습니다. 파일 생성 옵션(CreationScheduleOption 열거 타입)을 일별 혹은 주별(weekly)로 설정하면 파일 이름(FileNamePrefix) 뒤에 로그 생성 날짜가 붙습니다. 예를들어 파일 생성 옵션을 일주일로 설정하면 매주 월요일마다 새로운 파일이 생성되며, 매일 옵션을 사용하면 매일 새로운 파일에 로그를 기록합니다.

    또한, 파일 크기가 일정 수준에 도달하면 새로운 파일을 생성하도록 할 수도 있습니다. 이 경우 새롭게 생성되는 파일 명 뒤에 일련 번호가 붙게 됩니다. 일자별 옵션과 파일 크기 제한은 동시에 설정이 가능하며 이 경우 파일 명 뒤에 날짜와 일련 번호가 동시에 추가됩니다.

    MyLogFile_2021-12-01.log
MyLogFile_2021-12-01__1.log
MyLogFile_2021-12-01__2.log
MyLogFile_2021-12-01__3.log

  • 손쉬운 디렉터리 지정

    로그 파일을 생성할 디렉터리를 지정할 때 절대 경로와 어플리케이션 디렉터리(exe 가 존재하는 디렉터리)로부터 상대 경로 중 하나를 사용할 수 있습니다.

    디렉터리 지정 시 ~ 문자를 사용하여 어플리케이션 디렉터리로부터의 상대 경로를 나타내거나, |temp|, |appdata| 와 같은 예약어를 사용하여 TEMP 디렉터리, App_Data 디렉터리를 나타낼 수 있습니다.

  • 높은 동시성

    FoxTextFileLogger 는 여러 스레드가 하나의 로그 파일에 로그를 기록할 때 발생할 수 있는 동시성 문제를 완벽하게 제어합니다. 단순한 배타적 잠금을 사용하는 대신 reader/writer 잠금을 사용하여 잠금 발생을 최소화 하여 성능 저하를 막습니다.

    또한 NeoDEEX 기반의 여러 어플리케이션이 하나의 로그 파일에 로그를 기록할 때를 대비하여 전역 배타적 잠금 기능도 제공합니다. 이 전역 배타적 잠금은 IIS의 프로세스 풀 환경에서 작업 프로세스(w3wp.exe)가 2개 이상인 상황에서도 로그가 깨지지 않고 정상적으로 기록되도록 해 줍니다.

Configuration

로깅 구성 설정을 통해 FoxTextFileLogger 에 대한 설정을 수행하고 사용하는 것이 가장 일반적이고 권장되는 방법입니다. "logging:providers" 혹은 "logging:loggers" 섹션에서 FoxTextFileLogger 의 생성 속성을 지정할 때 "properties" 속성에 사용할 수 있는 옵션은 다음과 같습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "logging": {
    "providers": {
      "TextFileProvider": {
        "providerType": "NeoDEEX.Diagnostics.Loggers.FoxTextFileLoggerProvider",
        "properties": {
          "fileprefix": "MyLog",
          "directory": "~/Logs",
          "creation": "None",
          "maxsize": 16,
          "encoding": "ks_c_5601-1987",
          "exclusiveLock": false
        }
      }
    },
    "loggers": {
      "MyLogger": {
        "providerName": "TextFileProvider",
        "filter": "Verbose"
      },
      "YourLogger": {
        "providerName": "TextFileProvider",
        "filter": "Verbose",
        "properties": {
          "fileprefix": "YourLog",
          "creation": "Daily"
        }
      }
    }
  }
}

Note

"loggers" 섹션에 설정된 "properties" 속성은 "providers" 섹션의 설정을 오버라이드 합니다.

  • "fileprefix" 속성

    로그를 기록할 파일의 이름을 지정합니다. 확장자는 .log 로 고정됩니다. "creation" 속성 값에 의해 파일 이름 뒤에 날짜가 붙을 수 있으며, "maxsize" 속성에 의해 날짜 뒤에 일련 번호가 붙을 수 있습니다.

    이 속성의 디폴트 값은 NeoDEEX 입니다.

  • "directory" 속성

    로그 파일을 생성할 디렉터리를 지정합니다. 디렉터리가 존재하지 않는 경우 생성을 시도 합니다. 디렉터리 생성은 권한 부족으로 실패할 수도 있습니다.

    디렉터리는 어플리케이션 디렉터리로부터의 상대 경로를 사용하거나 절대 경로를 사용할 수도 있습니다. 디렉터리 이름에 ~ 문자를 사용하여 어플리케이션 디렉터리를 나타낼 수도 있습니다. 예를 들어 ~/Logs 는 어플리케이션 디렉터리의 하위 디렉터리인 Logs 폴더를 나타냅니다.

    "directory" 속성에는 특정 폴더를 사용하도록 예약어를 사용할 수 있습니다. 사용 가능한 예약어는 |auto|, |temp|, |appdata| 입니다. 이 속성의 디폴트 값은 |auto| 입니다.

    • |auto| 는 호스팅 환경에서는 임시 디렉터리를 사용하고 그 외의 상황에서는 어플리케이션 디렉터리를 사용합니다.

    • |temp| 는 임시 디렉터리의 하위 FoxLog 디렉터리(%TEMP%/FoxLog)를 사용합니다.

    • |appdata| 는 어플리케이션 디렉터리의 하위 디렉터리인 App_Data 디렉터리를 사용합니다. ASP.NET 어플리케이션과 같은 환경에서는 디렉터리 생성 및 파일 쓰기에 제약이 많은 상황이지만 App_Data 디렉터리는 대개 쓰기가 허용되기 때문에 이 디렉터리에 로그를 남기고자 할 때 사용할 수 있습니다.

  • "creation" 속성

    날짜에 따라 로그 파일의 생성 주기를 설정합니다. 사용 가능한 값은 다음과 같습니다. 이 속성의 기본값은 Daily 입니다.

    • None

      날짜에 상관없이 파일 명을 유지합니다. "fileprefix" 속성에 지정된 파일 이름 뒤에 날짜가 붙지 않습니다.

      MyLog.log

    • Daily

      매일 새로운 로그 파일을 생성합니다. "fileprefix" 속성으로 지정된 파일 이름 뒤에 날짜가 붙습니다.

      YourLog_2022-04-21.log

    • Weekly

      매주 월요일 로그 파일을 생성합니다. "fileprefix" 속성으로 지정된 파일 이름 뒤에 날짜가 붙습니다.

      YourLog_2022-04-18.log

  • "maxsize" 속성

    로그 파일의 최대 크기를 제한합니다. 로그 파일의 크기가 이 속성이 지정하는 가을 초과 하는 경우 새로운 로그 파일이 생성되며 파일 이름 뒤에 일련 번호가 붙게 됩니다. 로그 파일의 크기에 KB 혹은 MB를 붙여 크기 킬로 바이트 혹은 메가 바이트 단위로 크기 지정을 할 수 있습니다. 이 값이 0 으로 지정되면 크기 제약이 없습니다. 이 속성의 기본값은 0 입니다.

    YourLog_2022-04-21.log
YourLog_2022-04-21__1.log
YourLog_2022-04-21__2.log

  • "encoding" 속성

    로그 텍스트 파일의 인코딩을 설정 합니다. 사용 가능한 설정 값은 System.Text.Encoding 클래스 문서를 참고 하십시요. 이 속성의 기본값은 utf-8 입니다.

    Warning

    .net core 는 .net framework와 달리 기본적으로 사용한 인코딩에 제약이 있습니다. 따라서 ks_c_5601-1987, euc-kr 과 같은 인코딩을 사용하기 위해서는 System.Text.Encoding.CodePages 패키지를 참조하고 인코딩을 등록해 주어야 합니다.

    1
2
    using System.Text;
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

  • "exclusiveLock" 속성

    FoxTextFileLogger 는 여러 스레드가 하나의 로거에 로그를 기록할 때 발생할 수 있는 경쟁 상황(race condition)을 처리하기 위한 잠금 기능을 가지고 있습니다. 하지만 여러 어플리케이션(프로세스)가 하나의 로그 파일에 로그를 기록하는 상황에서의 잠금은 기본적으로 제공하지 않습니다. 여러 어플리케이션이 하나의 로그 파일에 로그를 기록하는 상황이라면 이 속성을 true 로 지정하면 됩니다. 이 속성의 기본값은 false 입니다.

    이 속성이 true 로 지정되면 로거는 전역 잠금 객체를 생성하고 로그 기록 시 이 잠금을 사용하게 됩니다. 따라서 여러 어플리케이션이 하나의 로그 파일에 로그를 기록하는 상황에서도 로그가 깨지지 않습니다. 다만 전역 잠금을 추가적으로 사용하기 때문에 추가적인 오버헤드가 발생합니다. 로그 파일이 단일 어플리케이션에 의해서만 사용되는 경우 이 속성을 true 로 지정하지 마십시요.

    Note

    여러 어플리케이션이 하나의 로그 파일에 접근하는 상황은 IIS의 응용 프로그램 풀에서 작업 프로세스를 2개 이상으로 지정하는 상황이 가장 전형적인 예 입니다.

FoxTextFileLogger class

FoxTextFileLogger 를 사용하여 로그를 기록하는 가장 쉽고 일반적인 방법은 로깅 구성 설정을 통해 로거의 속성을 명시하고 생성하는 것입니다. 하지만 가끔 구성 설정 파일을 사용하기 어려운 상황에서는 직접 FoxTextFileLogger 클래스를 사용하여 로거를 생성하고 사용해야 합니다.

또한, 로깅 구성 설정을 사용하고 GetLogger 메서드 호출을 통해 로거에 대한 IFoxLog 인터페이스를 획득했을 지라도 FoxTextFileLogger 클래스 타입을 통해 필요한 로거 정보를 획득할 수 있습니다.

1
2
3
4
5
6
7
8
9
IFoxLog log = FoxLogManager.GetLogger("MyLogger");
FoxTextFileLogger logger = log as FoxTextFileLooger;
if (logger != null)
{
    Console.WriteLine($"LogFile :{logger.FilePath}");
}

// 수행 결과
// LogFile: D:\TextFileLoggerSample\bin\Debug\net6.0\Logs\MyLog__3.log

Initialization

FoxTextFileLogger 객체를 생성하기 위해서는 다음 생성자 들 중 하나를 사용할 수 있습니다. 파일 생성 주기, 파일 크기 등의 옵션들이 명시되지 않는 생성자를 사용하면 기본값이 사용됩니다. 이들 옵션의 기본값은 구성 설정에서 사용하는 것과 동일합니다.

1
2
3
4
5
public FoxTextFileLogger(string name);
public FoxTextFileLogger(string name, string filePrefix);
public FoxTextFileLogger(string name, string filePrefix, string? directory);
public FoxTextFileLogger(string name, string filePrefix, string? directory, bool exclusiveLock);
public FoxTextFileLogger(string name, string filePrefix, string? directory, CreationScheduleOption creationSchedule, long maxFileSize, Encoding encoding, bool exclusiveLock = false);

생성된 FoxTextFileLogger 객체를 직접 사용하는 것 보다는 FoxLogManager 에 등록하여 사용하는 것이 Fox Logging이 제공하는 전반적인 로깅 인프라를 활용할 수 있습니다. RegisterLogger 메서드를 호출하여 다음과 같이 등록할 수 있습니다.

1
2
FoxTextFileLogger logger = new("HisLogger", "HisLog", "~\\Logs");
FoxLogManager.RegisterLogger(logger);

이제 생성된 FoxTextFileLogger 는 "logging:loggers" 섹션을 통해 생성된 로거와 동일하게 사용이 가능합니다.

Major properties

FoxTextFileLogger 클래스는 여러 속성들을 제공합니다. 이들은 대부분 읽기 전용이며 구성 설정 혹은 생성자를 통해 설정된 값들을 그대로 반환하거나 실질적인 값을 반환합니다.

  • FilePrefix, DirectoryPath, 'CreationSchedule', 'MaxFileSize' 속성

    구성 설정 혹은 생성자를 통해 전달된 로그 파일 명("filePrefix")과 디렉터리 명("directory"), 파일 생성 주기("creation"), 파일 최대 크기("maxsize")를 반환합니다.

  • EffectiveDirectory 속성

    EffectiveDirectory 속성은 DirectoryPath 속성에 전달된 상대 경로, 예약어 등을 모두 고려하여 실질적으로 로그 파일이 생성되는 디렉터리를 절대 경로로 반환합니다.

  • FilePath 속성

    로그 파일 디렉터리(EffectiveDirectory), 로그 파일 생성 주기(CreationSchedule) 및 파일 최대 크기(MaxFileSize)에 의해 설정된 파일 인덱스를 포함하여 실질적인 로그 파일의 경로를 절대 경로로 반환합니다.

    Warning

    로그가 기록되지 않으면 파일이 생성되지 않기 때문에 FilePath 속성이 지시하는 경로에 파일이 존재하지 않을 수도 있습니다.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    Console.WriteLine($"FilePrefix: {logger1.FilePrefix}");
Console.WriteLine($"DirectoryPath: {logger1.DirectoryPath}");
Console.WriteLine($"CreationSchedule: {logger1.CreationSchedule}");
Console.WriteLine($"MaxFileSize: {logger1.MaxFileSize}");
Console.WriteLine($"EffectiveDirectory: {logger1.EffectiveDirectory}");
Console.WriteLine($"FilePath: {logger1.FilePath}");
// 출력 내용
// FilePrefix: YourLog
// DirectoryPath: ~/Logs
// CreationSchedule: Daily
// MaxFileSize: 16
// EffectiveDirectory: D:\FoxLoggingSamples\TextFileLoggerSample\bin\Debug\net6.0\Logs
// FilePath: D:\FoxLoggingSamples\TextFileLoggerSample\bin\Debug\net6.0\Logs\YourLog_2022-05-03__1.log

  • EncodingName, Encoding 속성

    EncodingName 속성은 구설 설정을 통해 전달된 텍스트 파일 인코딩 이름을 나타내며 Encoding 속성은 텍스트 로그 파일 기록에 사용되는 인코딩 객체를 반환합니다.

  • ExclusiveLock 속성

    구성 설정 혹은 생성자를 통해 설정된 배타적 잠금 여부를 반환합니다.

  • LogDayOfWeek 정적(static) 속성

    유일하게 읽기/쓰기가 가능한 속성으로 로그 파일 생성 주기(CreationSchedule 속성)가 Weekly 로 설정된 경우 로그 파일을 생성할 요일을 지정합니다. 기본값은 1 으로 매주 월요일 날짜로 로그 파일이 생성됩니다. 이 값을 변경하면, 날짜가 바뀌고 Weelky 로 설정된 로거가 로그를 기록하여 새로운 파일을 생성해야 할 때 효과가 나타납니다.

    Warning

    혼동을 막기 위해 LogDayOfWeek 속성은 어플리케이션 시작시 설정하고 그 이후에는 변경하지 않는 것을 권장합니다.

FoxTextFileLoggerProvider class

FoxTextFileLoggerProvider 클래스는 IFoxLogProvider 인터페이스를 구현하는 클래스로서 로깅 구성 설정에 의해 생성되어 FoxTextFileLogger 객체를 생성하기 위해 사용됩니다. FoxLogManager 는 IFoxLoggerProvider 인터페이스의 CrateLogger 메서드를 호출하며 이 때 구성 설정의 properties 속성의 설정을 FoxLoggerPropertiesCollection 객체로 전달합니다.

구성 설정 파일을 사용하기 어려운 환경에서는 생성자를 통해 FoxTextFileLogger 객체를 직접 생성하거나 FoxTextFileLoggerProvider 객체를 통해 FoxTextFileLogger 객체를 생성할 수 있습니다.

Tip

구성 설정을 사용하지 않는 경우, FoxTextFileLoggerProvider 클래스를 사용하여 FoxTextFileLogger 객체를 생성할 때 얻을 수 있는 장점이 없으므로 생성자를 통해 직접 FoxTextFileLogger 객체를 생성하는 것이 보다 편리합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Dictionary<string, string> dic = new()
{
    { "filePrefix", "HisLog"},
    { "directory", "~/Log"},
    { "maxSize", "64MB"}
};
FoxLoggerPropertyCollection properties = new(dic); 
FoxTextFileLoggerProvider provider = new("theProvider", properties);
FoxTextFileLogger logger3 = (FoxTextFileLogger)provider.CreateLogger("HerLogger", FoxLoggerPropertyCollection.Empty);
Console.WriteLine($"FilePath: {logger3.FilePath}");
Console.WriteLine($"MaxFileSize: {logger3.MaxFileSize}");