NLog

NLog란?

NLog is a flexible and free logging platform for various .NET platforms, including .NET standard.
NLog는 .NET standard 를 비롯한 다양한 .NET 플랫폼을 위한 유연하고 자유로운 로깅 플랫폼입니다.
https://nlog-project.org

Configuration

config 파일을 사용하는 방법과 코드에서 설정하는 방법이 있습니다.
두가지 방법은 함께 사용할 수 있습니다.

1. Config 파일 사용

config 파일을 아래 순서대로 검색하다 처음 검색된 파일을 사용합니다.

독립 실행형 응용 프로그램 (.exe)

• 표준 응용프로그램 구성 파일 app.config (ex: 프로그램명.exe.config)
• 응용 프로그램 폴더에 있는 '프로그램명.exe.nlog'
• 응용 프로그램 폴더에 있는 'NLog.config'
• NLog.dll이 위치한 폴더에 있는 'NLog.dll.nlog'
  (NLog.dll이 GAC(Global Assembly Cache)에 설치되지 않은 경우에만)

---

ASP.NET 응용 프로그램

• 표준 응용 프로그램 구성 파일 'web.config'
• web.config 파일이 위치한 폴더에 있는 'web.nlog'
• 응용 프로그램의 폴더에 있는 'NLog.config'
• NLog.dll이 위치한 폴더에 있는 'NLog.dll.nlog'
  (NLog.dll이 GAC(Global Assembly Cache)에 설치되지 않은 경우에만)

2. 코드에서 설정

Configuration API 를 사용하여 프로그래밍 방식으로 코드에서 설정할 수 있습니다.
모든 속성은 config 파일의 구조와 동일합니다.

Config 파일

0. 파일 구조

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     
	<!-- 변수 선언 -->

	<!-- Targets : 출력 대상 정의 -->
    <targets>
    </targets>

	<!-- Rules : 출력 정책 설정 -->
    <rules>
    </rules>
</nlog>

1. 기본 옵션

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      autoReload="Boolean"
      internalLogFile="String"
      keepVariablesOnReload="Boolean"/>

• autoReload (Boolean) : config 파일의 변경사항을 자동으로 다시 로드할지 여부
• internalLogFile (String) : 내부 로그 파일 경로
• keepVariablesOnReload (Boolean) : 런타임에 할당된 변수를 config 가 다시 로드될 때 유지할지 여부
• 그 외 : internalLogToConsole, internalLogToConsoleError, internalLogLevel, globalThreshold, throwExceptions, throwConfigExceptions, internalLogToTrace, internalLogIncludeTimestamp, useInvariantCulture, parseMessageTemplates

2. 변수

변수는 Configuration API 를 사용하여 변경, 삭제 및 생성할 수 있습니다.

변수 정의

<variable name="변수명" value="값"/>

변수 사용

${변수명} - 정적 모드 (또는 상수 모드)
${var:변수명} - 동적 모드

3. targets

출력 대상과 레이아웃을 정의합니다.
대상 - 콘솔, 파일, DB, 메일, 클라우드, 로그 뷰어 (NLog, Log4j, Windows), 윈폼 등 (v5.2.7 기준 101개)
레이아웃 - 텍스트, JSON, CVS, Log4JXml, XML 등 (v5.2.7 기준 13개)
(https://nlog-project.org/config/?tab=targets)

Console

<target xsi:type="Console"
		name="String"
        layout="Layout"
        autoFlush="Boolean"
        error="Boolean"/>

• name (String) - 대상 이름
• layout (Layout) - 로그 메시지 형태
• autoFlush (Boolean) - 콘솔 출력 후 자동 플러시 여부
• error (Boolean) - 표준 출력 대신 표준 오류로 보낼지 여부
• 그 외 - header, footer, detectConsoleAvailable, encoding, writeBuffer, optimizeBufferReuse

---

File

<target xsi:type="File"
        name="xs:string"
        layout="Layout"
        maxArchiveDays="Integer"
        archiveEvery="Enum"
        archiveAboveSize="Long"
        maxArchiveFiles="Integer"
        archiveOldFileOnStartup="Boolean"
        fileName="Layout"/>

• name (String) - 대상 이름
• layout (Layout) - 로그 메시지 형태
• maxArchiveDays (Integer) - 아카이브 파일 보관 기간
• archiveEvery (Enum) - 로그 파일 아카이빙 주기 (Day, Sunday 등)
• archiveAboveSize (Long) - 로그 파일 아카이빙 크기 (바이트)
• maxArchiveFiles (Integer) - 아카이브 파일의 최대 개수
• archiveOldFileOnStartup (Boolean) - 시작 시 기존 로그 파일을 아카이빙할지 여부
• fileName (Layout) - 파일명
• 그 외 - header, footer, encoding, lineEnding, enableArchiveFileCompression, archiveNumbering, archiveFileName, archiveFileKind, writeFooterOnArchivingOnly, maxLogFilenames, deleteOldFileOnStartup, fileAttributes, createDirs, cleanupFileName, archiveOldFileOnStartupAboveSize, archiveDateFormat, enableFileDelete, writeBom, replaceFileContentsOnEachWrite, forceMutexConcurrentWrites, forceManaged, fileNameKind, optimizeBufferReuse, networkWrites, openFileCacheTimeout, openFileCacheSize, keepFileOpen, discardAll, concurrentWrites, concurrentWriteAttempts, concurrentWriteAttemptDelay, bufferSize, openFileFlushTimeout, autoFlush

---

Database

<target xsi:type="Database"
        name="String"
        keepConnection="Boolean"
        dbProvider="String"
        dbHost="Layout"
        dbDatabase="Layout"
        dbUserName="Layout"
        dbPassword="Layout"
        connectionString="Layout"
        commandText="Layout">

  <parameter name="String"
             layout="Layout"
             format="String"/>
</target>

• name (String) - 대상 이름
• keepConnection (Boolean) - DB 연결 유지 여부
• dbProvider (String) - DB 공급자 이름 (connectionString 미제공 시 'Provider=')
• dbHost (Layout) - DB 호스트명 (connectionString 미설정 시 'Server=')
• dbDatabase (Layout) - DB 이름 (connectionString 미설정 시 'Database=')
• dbUserName (Layout) - DB 사용자 이름 (connectionString 미설정 시 'User ID=')
• dbPassword (Layout) - DB 암호 (connectionString 미설정 시 'Password=')
• connectionString (Layout) - DB 연결 문자열
• commandText (Layout) - SQL 명령어 (INSERT 쿼리 등)
• parameter - SQL 명령어 파라미터
• parameter/name (String) - 파라미터 이름
• parameter/layout (Layout) - 파라미터 형태
• 그외 - keepConnection, connectionproperty, commandProperty, installConnectionString, install-command, uninstall-command, isolationLevel, optimizeBufferReuse, commandType, parameter/dbType, parameter/size, parameter/precision, parameter/scale, parameter/parameterType, parameter/allowDbNull, parameter/format, parameter/culture

4. rules

출력 대상이나 로그 레벨에 대한 출력 정책을 설정합니다.
로그 레벨 - Trace (0) > Debug (1) > Info (2) > Warn (3) > Error (4) > Fatal (5)

<logger name="String"
		levels="String"
		minlevel="Enum"
		maxlevel="Enum"
		level="Enum"
		writeTo="String"
		final="Boolean"
		enabled="Boolean"
		ruleName="String" />

• name (String) - 로깅할 로거 이름 (*, ? 사용 가능)
• levels (String) - 로깅할 레벨 목록 (','로 구분하여 나열)
• minlevel (Enum) - 로깅할 최소 레벨
• maxlevel (Enum) - 로깅할 최대 레벨
• level (Enum) - 로깅할 레벨
• writeTo (String) - 로깅할 출력 대상 이름 목록 (','로 구분하여 나열)
• final (Boolean) - 일치하는 규칙이 있는 경우 이후 규칙 처리 중지 여부
• enabled (Boolean) - 규칙 비활성화
• ruleName (String) - 규칙 이름

5. 레이아웃 렌더러

레이아웃에서 사용되는 템플릿 매크로입니다.
(v5.2.7 기준 143개. https://nlog-project.org/config/?tab=layout-renderers)

${level} - 로그 레벨
${message} - 로그 메시지

호출 위치 및 호출 스택
${callsite-filename} - 호출 파일명
${callsite-linenumber} - 호출 줄 번호
${stacktrace} - 스택 트레이스

조건
${when:when=조건:inner=값1:else=값2} - 조건에 따라 값 선택
${값:whenempty=대체값} - 값이 비어있을 경우 값 대체

컨텍스트 정보
${변수명} - NLog 로깅 변수값

카운터
${guid} - GUID
${sequenceid} - 로그 시퀀스 아이디

날짜 및 시간
${date}, ${longdate}, ${shortdate} - 현재 날짜 및 시간
${ticks} - 현재 날짜 및 시간의 ticks

인코딩 및 문자열 변환
${값:padding=개수} - 개수만큼 왼쪽 패딩
${replace:inner=값:searchFor=찾기:replaceWith=바꾸기} - 문자열 바꾸기
${substring:inner=값:start=N1:length=N2} - 문자열 자르기
${값:trimWhiteSpace=true} - 공백 제거
${값:uppercase=true}, ${lowercase:값} - 대/소문자 출력
${값:json-encode=true}, ${값:xmlEncode=true} - json/xml 인코딩

환경 및 구성 파일
${appsetting:item=이름} - app 설정 값 (app.config)
${environment:변수명} - 환경 변수 값

파일 및 디렉토리
${basedir}, ${processdir}, ${tempdir} - 디렉토리 경로
${file-contents:fileName=파일명} - 파일 내용

사용자 식별
${environment-user} - 사용자/도메인 정보

프로세스, 스레드 및 어셈블리
${appdomain} - app 도메인
${assembly-version} - 어셈블리 버전
${hostname} - 호스트 이름
${local-ip} - 로컬 IP 주소
${processid}, ${processname} - 프로세스 ID/이름
${threadid}, ${threadname} - 스레드 ID/이름

예제

1. NuGet 설치

• NLog
• NLog.Config (옵션)
  

2. NLog.config 작성

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <variable name="logLayout" value="[${date:format=HH\:mm\:ss.fff}] | ${level:padding=-5} | ${message}"/>
  <variable name="logDir" value="${currentdir}\log\${date:format=yyyyMMdd_HH}"/>

  <targets>
    <target xsi:type="Console" name="console" layout="${stacktrace} ${var:logLayout}"/>
	<target xsi:type="File" name="file" layout="${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}.txt" maxArchiveDays="1"/>
	<target xsi:type="File" name="file-err" layout="${callsite-filename} ${callsite-linenumber} ${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}_err.txt" archiveOldFileOnStartup="True"/>

  <rules>
	<logger writeTo="console"/>
	<logger minlevel="Info" maxlevel="Error" writeTo="file"/>
	<logger level="Error" writeTo="file-err"/>
  </rules>
</nlog>

3. 코드 작성

using NLog;

namespace NLogTest
{
    class Program
    {
        private static Logger _logger = LogManager.GetCurrentClassLogger();
        static void Main(string[] args)
        {
            _logger.Debug("[Main] Debug 로그");
            _logger.Info("[Main] Info 로그");
            _logger.Error("[Main] Error 로그");
            _logger.Fatal("[Main] Fatal 로그");

            Test1();
        }

        static void Test1()
        {
            _logger.Debug("[Test1] Debug 로그");
            _logger.Info("[Test1] Info 로그");
            _logger.Error("[Test1] Error 로그");
            _logger.Fatal("[Test1] Fatal 로그");

            Test2();
        }

        static void Test2()
        {
            _logger.Debug("[Test2] Debug 로그");
            _logger.Info("[Test2] Info 로그");
            _logger.Error("[Test2] Error 로그");
            _logger.Fatal("[Test2] Fatal 로그");
        }
    }
}

4. 결과

Console

<target xsi:type="Console" name="console" layout="${stacktrace} ${var:logLayout}"/>
<logger writeTo="console"/>

• 모든 레벨 출력
• 스택 트레이스 출력 (Program.Main => Program.Test1 => Program.Test2)

---

File

<target xsi:type="File" name="file" layout="${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}.txt" maxArchiveDays="1"/>
<logger minlevel="Info" maxlevel="Error" writeTo="file"/>

• Info ~ Error 레벨 로그 출력

<target xsi:type="File" name="file-err" layout="${callsite-filename} ${callsite-linenumber} ${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}_err.txt" archiveOldFileOnStartup="True"/>
<logger level="Error" writeTo="file-err"/>

• Error 레벨 로그 출력
• 호출 파일명 및 줄 번호 출력 (C:\Source\NLogTest\NLogTest\Program.cs 32)

---

2023.12.20 2회 실행

2023.12.23 1회 실행

<target xsi:type="File" name="file" layout="${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}.txt" maxArchiveDays="1"/>
<target xsi:type="File" name="file-err" layout="${callsite-filename} ${callsite-linenumber} ${var:logLayout}" fileName="${var:logDir}\log_${date:yyyyMMdd}_err.txt" archiveOldFileOnStartup="True"/>

• 보관 기간이 지난 아카이브 파일 자동 삭제 (log_20231220.txt)
• 시작 시 기존 로그 파일 아카이빙 (log_20231220_err.txt -> log_20231220_err.0.txt)