NLog 設定項目 詳細

NLogの設定

NLogのチュートリアルやサンプルやAPI仕様などは、以下のページ（英語）にあります。
https://github.com/nlog/nlog/wiki
設定（構成）に関してはConfiguration Referenceという章に纏まっています。
ここは、そのページの抄訳になります。
誤字・誤訳・誤解釈などありましたら、本家ページでご確認してみてください。ついでにコメント頂けると参考になります。

構成ファイル

NLogの構成はXML形式のファイルで行う。

構成ファイルの配置場所

Exeアプリの場合

• 標準のアプリケーション構成ファイル(applicationname.exe.config)
• Exeの実行フォルダにあるapplicationname.exe.nlogファイル
• Exeの実行フォルダにあるNLog.configファイル
• NLogがGACとしてインスコされてない場合はNLog.dllが配置されたフォルダにNLog.dll.nlog

ASP.NETの場合

• 標準のWeb構成ファイル(web.config)
• web.configと同じフォルダに配置されたweb.nlog.config
• アプリケーション実行フォルダにあるNLog.configファイル
• NLogがGACとしてインスコされてない場合はNLog.dllが配置されたフォルダにNLog.dll.nlog

.NET Compact Framework の場合

標準のアプリケーション構成ファイルが使えないので以下となる。

• Exeの実行フォルダにあるapplicationname.exe.nlogファイル
• Exeの実行フォルダにあるNLog.configファイル
• NLogがGACとしてインスコされてない場合はNLog.dllが配置されたフォルダにNLog.dll.nlog

構成ファイルの書式

NLogでは２種類の構成ファイル書式がある。
１．標準のアプリケーション構成ファイル内に記述する書式
２．別個のファイルに記述されるシンプルな書式

<configuration>
  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
  </configSections>
  <nlog>
  </nlog>
</configuration>

VisualStudioでインテリセンスを有効にするには以下の指定をする。

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

注意
・ネームスペースを使わない場合は大文字小文字の区別なし
・ネームスペースを使う場合は大文字小文字の区別あり

<nlog />　のタグがルートになり、この子要素として以下のタグで指定する。 最初の２つが必須で、それ以外は任意。

<targets />　ログのターゲット／出力を定義する
<rules />　ログのルーティング規則を定義する
<extensions />　*.dllファイルから拡張機能を読み込む
<include />　他の構成ファイルを読み込む
<variable />　構成ファイルの変数の値を設定する

ターゲット

<targets />　セクションにログのターゲットを定義する。以下の２つの属性を含む。

• name：ターゲット名
• type：ターゲット種別（ファイルとかデータベースなど）

これら２つの属性に加えて、解析やトレースに役立つようなパラメータを指定することができる。
各ターゲット毎に指定可能なパラメータは違うので詳細な仕様は本家ページを参照のこと。
また、インテリセンスもVisualStudioから入手可能である。

※ターゲットのAPI　⇒　https://github.com/nlog/nlog/wiki/Targets
※ターゲットの実装方法　⇒　https://github.com/nlog/nlog/wiki/How%20to%20write%20a%20Target

規則

<rules />　セクションにルーティング規則を定義する。 単純なテーブル構成であり、ソースとログ名とログレベルとから成るターゲットのリストを定義する。
複数の規則が定義されている場合は、リストの順番で規則に適合するかをチェックする。
チェックに適合した場合に、その規則に定義されているターゲットでログ出力される。
規則にFinalの指定がある場合はそれ以下の規則は適用されない。

それぞれのルーティングテーブルエントリは<logger />タグの要素であり、以下の属性をもつ。

• name：ソースまたはロガーの名前（ワイルドカード*もOK)
• minlevel：最小ログレベル
• maxlevel：最大ログレベル
• level：（単数）ログレベル
• levels：（複数）ログレベル。カンマ区切りで指定する
• writeTo：カンマ区切りのターゲットリスト。
• final：最後の適合となる規則。以降は適用されない。
• enabled：enabledをdiableに指定することにより規則は適用されなくなる。

レベルに関するキーワード(level,levels,minlevel,maxlevel)の一つ以上を必ず含む必要がある。
これらは以下の順番で評価される。
１．level
２．levels
３．minlevel/maxlevel（この二つは同じ優先度）
４．キーワードなし（すべてのレベルが対象）

レイアウトとレイアウトレンダリング

NLogの最も強力な機能の一つがレイアウトを使えること。
これは${}で囲まれたタグで記述されるテキストである。
このタグはレイアウトレンダラーと呼ばれ、ログ出力に関する指定された情報を挿入するために使われる。
各所で使用され、例えば画面上に表示したりファイルに送信したりする情報を制御したり、出力先のファイル名を制御したりする。

例えば、コンソールに現在時刻・クラス名とメソッドとログレベルとメッセージとを出力するには以下のように記述する。

<target name="c" xsi:type="Console" layout="${longdate} ${callsite} ${level} ${message}" />

ファイル名自体を定義するには以下のように記述する。

<target name="f" xsi:type="File" fileName="${logger}.txt"/>

インクルードファイル

<include />セクションを使う。設定が複数のファイルに定義される場合に、他のファイルを読み込むための設定である。

<include file="${basedir}/${machinename}.config"/>

ignoreError="true"の指定をすることができる。
デフォルト値はfalseであり、明示的にtrue設定された場合は、指定ファイルがないとかフォーマットエラーであるといった例外が通知されるようになる。構成ファイル自体の不具合解析時に使う

変数

複雑だったり繰り返し使われたりするような場合に変数を定義することができる

<variable name="var" value="xxx" />

一度定義されものは ${var}により使用することができる。

自動再構成

構成ファイルに定義されている設定内容はアプリケーション起動時に自動的に読み込まれる。
WindowsServiceやWebシステムのように、プロセスが長期間稼働し続けるような場合に、アプリケーションを再起動させることなく設定を再読み込みさせるための機能。
以下の設定により、NLogが構成ファイルを監視し、変更があった場合に自動で読込を行う。

<nlog autoReload="true" />

変更監視の対処はインクルードファイルも含まれる。いづれか一つのファイルが変更された場合でも全体を再読み込みする。

トラブル解決のためのロギング

ちゃんと設定したはずにもかかわらず、ログ出力が行われない場合がある。
その原因はいろいろ想定され得るが、最も多いのが権限に起因するもの。
例えばASP.NETの場合、aspnet_wp.exe/w3wp.exeなどが物理ディスクへの書込権限を付与されていない場合など。

NLogはNLog自身が原因の場合に例外を出力しないが、以下の設定により出力させることができる。

• < nlog throwExceptions="true" /> この設定によりNLogに起因する例外がスローされるようになる。デプロイ時などで早い不具合原因の追究が可能となる。原因判明し次第、NLog起因でのアプリケーションクラッシュを興さないようFalse設定すること。
• < nlog internalLogFile="file.txt" />　この設定によりNLogは内部のデバッグメッセージを指定された特殊ファイルへ出力する
• < nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" />　内部ログレベルを指定する。ログレベルを上げるほど詳細な情報が出力される。
• < nlog internalLogToConsole="false|true" />　内部ログメッセージをコンソール出力するか否か
• < internalLogToConsoleError="false|true" />　内部ログメッセージをコンソールエラー出力するか否か

非同期プロセスとラッパーターゲット

NLogは以下のような機能を追加することにより、他のターゲットの機能をラップしたり合成したりできる。
・非同期プロセッシング（ターゲットを別のスレッドで実行させる）
・例外時のリトライ
・ロードバランシング
・バッファリング
・フィルタリング
・フェイルオーバー
構成ファイルでラッパーを定義するには、単純にターゲットノードをネストさせればよく、その階層も制限はない。
以下はリトライ機能と非同期とを付加させるサンプル。

<targets>
  <target name="n" xsi:type="AsyncWrapper">
    <target xsi:type="RetryingWrapper">
      <target xsi:type="File" fileName="${file}.txt" />
    </target>
  </target>
</targets>

非同期はよく使われるので、以下のように略記可能。

<nlog>
  <targets async="true">
    <!-- all targets in this section will automatically be asynchronous -->
  </targets>
</nlog>

デフォルトラッパー

複数のターゲットに同じラッパーを付与させる機能

<nlog>  
  <targets>  
    <default-wrapper xsi:type="AsyncWrapper">  
      <wrapper-target xsi:type="RetryingWrapper"/>  
    </default-wrapper>  
    <target name="n1" xsi:type="Network" address="tcp://localhost:4001"/>  
    <target name="n2" xsi:type="Network" address="tcp://localhost:4002"/>  
    <target name="n3" xsi:type="Network" address="tcp://localhost:4003"/>  
  </targets>  
</nlog>

デフォルトターゲットパラメータ

すべてのターゲットに同じパラメータの設定を付与する。

<nlog>
  <targets>
    <default-target-parameters xsi:type="File" keepFileOpen="false"/>
    <target name="f1" xsi:type="File" fileName="f1.txt"/>
    <target name="f2" xsi:type="File" fileName="f2.txt"/>
    <target name="f3" xsi:type="File" fileName="f3.txt"/>
  </targets>
</nlog>

エスケープ

設定ファイルはXML形式なので「＜」や「＞」などは「＆ｌｔ；」「＆ｇｔ；」へのエスケープ処理が必要
レイアウト内では「｝」のエスケープが必要。ネストされてる場合は不要
・ ${appdomain:format={1\}{0\}}
・ ${rot13:inner=${ndc:topFrames=3:separator=x}}

構成用のAPI

構成ファイルで定義する内容は、すべてプログラムとして記述することもできる。

使い方

NLogをコードで構成するには以下の手順が必要

１．LoggingConfigurationのインスタンスを生成して、これに構成を保持させる
２．Targetを継承する一つ以上のターゲットのインスタンスを生成
３．ターゲットのプロパティを設定
４．LoggingRuleクラスを介して規則を定義し、それをconfingurationのLoggingRulesに追加する
５．ConfigurationのインスタンスをLogManager.Configurationに設定することに有効にする

サンプル

以下は２つのターゲットを持つサンプルコード。
一つは色付きのコンソールへ、もう一方はDebug以上のレベルのログをファイル出力する

using NLog;
using NLog.Targets;
using NLog.Config;
using NLog.Win32.Targets;

class Example
{
    static void Main(string[] args)
    {
        // １．configuration を生成 
        var config = new LoggingConfiguration();

        // ２．targetを生成し configurationに設定 
        var consoleTarget = new ColoredConsoleTarget();
        config.AddTarget("console", consoleTarget);

        var fileTarget = new FileTarget();
        config.AddTarget("file", fileTarget);

        // ３．targetのプロパティを設定
        consoleTarget.Layout = @"${date:format=HH\\:MM\\:ss} ${logger} ${message}";
        fileTarget.FileName = "${basedir}/file.txt";
        fileTarget.Layout = "${message}";

        // ４．規則を定義
        var rule1 = new LoggingRule("*", LogLevel.Debug, consoleTarget);
        config.LoggingRules.Add(rule1);

        var rule2 = new LoggingRule("*", LogLevel.Debug, fileTarget);
        config.LoggingRules.Add(rule2);

        // ５．構成を有効化
        LogManager.Configuration = config;
    }
}

API

こちらのページにクラスライブラリあります。
http://nlog-project.org/documentation/v3.2.1/html/R_Project_NLog.htm

ターゲット

使用法

ターゲットは、メッセージを表示したり、記録したり、他の宛先へ送ったりするために使用される。
２種類あり、一つはメッセージを受け取り、それを処理する。もう一つは、メッセージを振り分けたりバッファリングしたりする。後者はラッパーと呼ばれる。

提供されているターゲット

※各項目の詳細な設定についてのリンクがあります。https://github.com/nlog/nlog/wiki/Targets

• AspNetTrace - ログメッセージを ASP.NET trace に書く
• AspResponse - ASP Response object を介してログメッセージを出力する
• Chainsaw - Log4JのビューワーであるChainsowのリモートインスタンスにログメッセージを送る
• ColoredConsole - コンソールにカスタマイズした色でログメッセージを書く
• Console - コンソールにログメッセージを書く
• Database - ADO.NETプロバイダーを使ってデータベースにログメッセージを書く
• Debug - モック（テスト用）
• Debugger - アタッチされたデバッガにログメッセージを書く
• EventLog - イベントログにログメッセージを書く
• File - ログメッセージをファイルに書く
• FormControl - 指定された名前のWindows.Forms.ControlのTextプロパティにロギングする
• LogReceiverService - WCFやWeb ServicesによるNLog Receiver Serviceにログメッセージを送る
• Mail - SMTP プロトコルを使って電子メールでログメッセージを送る
• Memory - プログラムで取得できるように、メモリ上のArrayListにログメッセージを書く
• MessageBox - ログメッセージをメッセージボックスを使ってポップアップ表示する
• MethodCall - ログメッセージ毎にパラメータを付与して指定された静的メソッドを呼ぶ
• MSMQ - MSMQで管理されている指定されたメッセージキューにログメッセージを書く
• Network - ネットワークを介してログメッセージを送る
• NLogViewer - リモートのNLog Viewerにログメッセージを送る
• Null - ログメッセージを破棄する。主にデバッグとかベンチマークで使用
• OutputDebugString - Win32 APIのOutputDebugString()でログメッセージを出力する
• PerfCounter - 書き込み処理毎に指定されたパフォーマンスカウンタをインクリメントする
• RichTextBox - 存在している、若しくは新規に作るRichTextBoxにログテキストをロギングする
• Trace - System.Diagnostics.Traceにログメッセージを送る
• WebService - ログメッセージ毎に指定されたWebServiceをコールする

ラッパーターゲット

• AspNetBufferingWrapper - ASP.NETのリクエスト中にログイベントをバッファし、リクエスト終了時にラップされたターゲットに送る
• AsyncWrapper - ターゲットが書き込み中は非同期でバッファリングを実行する
• AutoFlushWrapper - ラップされたターゲットに書き込み毎にフラッシュする
• BufferingWrapper - ログイベントをバッファし、ラップされたターゲットに纏めて送る。メールターゲットとの組み合わせで有用
• FallbackGroup - エラー時のフェイルバック機能を提供
• FilteringWrapper - 条件に基づきログエントリーをフィルタリングする
• ImpersonatingWrapper - 書き込み時に他のユーザに偽装
• PostFilteringWrapper - イベントのグループにより評価された複数の条件によりバッファされたログをフィルタリングする
• RandomizeGroup - ランダムに選択されたターゲットにログを送る
• RepeatingWrapper - 指定回数分それぞれおのログイベントを繰り返す
• RetryingWrapper - 書き込み失敗したら再挑戦
• RoundRobinGroup - ターゲットに順番にログイベントを振り分ける
• SplitGroup - 全てのターゲットにログイベントを書く

レイアウト

レイアウトはほとんどのターゲットにある属性の一つ。
レイアウト属性はロギングされる情報のフォーマットを決めるために使われる。
多くの定義済みのマクロつまりレイアウトレンダラーがあります。

デフォルトレイアウト

ターゲットがレイアウト属性を持つ場合は、自由に指定できるが、明示的な指定がない場合は以下のものが使用される。
${longdate}|${level:uppercase=true}|${logger}|${message}

定義済レイアウト

※各レイアウトの詳細な仕様はこちらのページからリンクされています。https://github.com/nlog/nlog/wiki/Layouts

• CsvLayout - CSVフォーマットイベント用特殊レイアウト
• LayoutWithHeaderAndFooter - ヘッダーとフッターとをサポートする特殊レイアウト
• Log4JXmlEventLayout - Log4jと共用可能なXMLエベント用特殊レイアウト
• SimpleLayout - 出力時の情報で代替される箇所を埋め込まれた文字列を表す

レイアウトレンダラー

レイアウトレンダラーとは各レイアウトで使われるテンプレートマクロのこと。

レイアウトレンダラー

※各レンダラーの詳細な仕様はこちらのページにリンクあり。https://github.com/nlog/nlog/wiki/Layout-Renderers

• ${appsetting} - アプリケーション構成の定義値
• ${asp-application} - ASP アプリケーションの変数
• ${aspnet-application} - ASP.NET アプリケーションの変数
• ${aspnet-request} - ASP.NET リクエスト変数
• ${aspnet-session} - ASP.NET セッション変数
• ${aspnet-sessionid} - ASP.NET セッションID
• ${aspnet-user-authtype} - ASP.NET ユーザー変数
• ${aspnet-user-identity} - ASP.NET ユーザー変数
• ${asp-request} - ASP リクエスト変数
• ${asp-session} - ASP セッション変数
• ${assembly-version} - アセンブリのバージョン
• ${basedir} - 実行中のアプリケーションの基底ディレクトリ
• ${callsite} - 呼び出し箇所（クラス名、メソッド名、ソース情報）
• ${counter} - カウント値（各レイアウトレンダリグ毎にインクリメント）
• ${date} - Current date and time.
• ${document-uri} - Silverlightアプリケーションを干すとしているHTMLページのURI
• ${environment} - 環境変数
• ${event-context} - ログイベントのコンテクストデータ
• ${exception} - 例外情報
• ${file-contents} - 指定されたファイルの内容
• ${gc} - ガベージコレクタについての情報
• ${gdc} - Global Diagnostic Context item. log4net.との共用で使用
• ${guid} - GUID(Globally-unique identifier)
• ${identity} - スレッド情報（スレッド名と認証情報）
• ${install-context} - インストールパラメーター (passed to InstallNLogConfig).
• ${level} - ログレベル
• ${literal} - 文字列
• ${log4jxmlevent} - log4のChainsawやNLogViewerと共用可能なXML書式の情報
• ${logger} - ロガー名
• ${longdate} - ログ時の時間(書式は yyyy-MM-dd HH:mm:ss.mmm)
• ${machinename} - プロセスが実行しているマシン名
• ${mdc} - Mapped Diagnostic Context item. log4net.との共用で使用
• ${message} - The formatted log message.
• ${ndc} - Nested Diagnostic Context item. log4net.との共用で使用.
• ${newline} - 改行文字
• ${nlogdir} - NLog.dllが配置されているフォルダ名
• ${performancecounter} - パフォーマンスカウンター
• ${processid} - プロセスID
• ${processinfo} - 実行中のプロセス情報
• ${processname} - プロセス名
• ${processtime} - プロセス時間（書式 HH:mm:ss.mmm）
• ${qpc} - QueryPerformanceCounter()での戻り値である高精度の時間。秒変換も可能
• ${registry} - レジストリ値
• ${shortdate} - 日付（書式 yyyy-MM-dd）
• ${sl-appinfo} - Silverlightアプリケーション情報
• ${specialfolder} - 特殊フォルダ（マイドキュメントやプログラムファイルズなど）へのパス
• ${stacktrace} - スタックトレース
• ${tempdir} - 一時フォルダ
• ${threadid} - カレントスレッドID
• ${threadname} - カレントスレッド名
• ${ticks} - 現在日時のTicks値
• ${time} - 時間（書式 HH:mm:ss.mmm）
• ${windows-identity} - TWI(Thread Windows identity)情報 (ユーザー名).

ラッパー　レイアウトレンダラー

※各ラッパーの詳細な仕様はこちらのページにリンクあり⇒https://github.com/nlog/nlog/wiki/Layout-Renderers

• ${cached} - キャッシング適用
• ${filesystem-normalize} - ファイル名として使用できない文字を安全な文字に置換
• ${json-encode} - JSON規則でエスケープ出力
• ${lowercase} - 小文字変換
• ${onexception} - 例外のみ出力
• ${pad} - パディング適用
• ${replace} - 置換
• ${rot13} - ROT-13で暗号化されたテキストの復号化
• ${trim-whitespace} - 空白削除
• ${uppercase} - 大文字変換
• ${url-encode} - URLを用いてのエンコード
• ${when} - 指定された条件に合致する場合のみ出力
• ${whenEmpty} - 他のレイアウトの出力結果が空白の場合に別のレイアウトを適用
• ${xml-encode} - XML準拠への置換

カスタム　レイアウトレンダラー

• ${gelf} - GELF(Graylog Extended Log Format)への変換

レイアウトへの値の引き渡し

沢山のレンダラーが定義され提供されているが、独自実装することも可能。
そのレイアウトレンダラーに特定の値を引き渡すには、イベントに独自のプロパティをコード側で追加する。 詳しくは${event-context}を参照のこと。

フィルター

ログ出力は構成ファイルの定義でフィルタリング可能

※各フィルタの詳細な仕様はこちらのページにリンクあり⇒https://github.com/nlog/nlog/wiki/Filters

提供されているフィルター

• when filter - 指定の条件に合致した場合

非推奨のフィルター

以下のフィルタではなくwhen filterを使うべし

• whenContains filter - 特定の文字列が含まれる場合
• whenEqual filter - 特定の文字列と等しい場合
• whenNotContains filter - 特定の文字列が含まれない場合
• whenNotEqual filter - 特定の文字列と等しくない場合

条件

when filterと一緒に使われる条件式。
Whenフィルターがアクションを起こすか否かを決定するのにつかわれる。

言語仕様

条件式は特殊なミニ言語で記述される。

• 関係演算子 - == , != , < , <= , >= , >(エスケープが必要な文字あり)
• ブール値演算子 - and , or , not
• リテラル文字列 - &{somerenderer}レンダラーを使う
• ブール値文字列 - true , false
• 数値型文字列 - 例えば 12345はInt型文字列で1234.56は浮動小数点型文字列
• ログレベル文字列 - LogLevel.Trace,LogLevel.Debug.....
• 予約語文字列 - level,message,logger
• 括弧 - 既定のプロパティとグループ式とを上書きする
• 関数 - stringとobjectとのテストを行う

関数

以下の関数が使える

• contains(s1,s2) - 第一引数の文字列に第二引数が含まれていればtrueを、いなければfalseを返却
• end-with(s1,s2) - 第一引数の文字列が第二引数の文字列で終わっていればtrueを、いなければfalseを返却
• equals(o1,o2) - 二つの引数が同じ場合はtrueを、そうでなければfalseを返却
• length(s) - 指定文字列の長さを返却
• start-with(s1,s2) - 第一引数の文字列が第二引数の文字列で始まっていればtrueを、いなければfalseを返却

例

<rules>
    <logger name="*" writeTo="file">
        <filters>
            <when condition="length('${message}') > 100" action="Ignore" />
            <when condition="equals('${logger}','MyApps.SomeClass')" action="Ignore" />
            <when condition="(level >= LogLevel.Debug and contains('${message}','PleaseDontLogThis')) or level==LogLevel.Warn" action="Ignore" />
            <when condition="not starts-with('${message}','PleaseLogThis')" action="Ignore" />
        </filters>
    </logger>
</rules>

拡張

静的公開クラスに静的メソッドを定義し、以下のようにConditionMethods,ConditionMethod属性をそれぞれ付与。

namespace MyExtensionNamespace 
{ 
    using System; 
    using NLog.Conditions; 

    [ConditionMethods] 
    public static class MyConditionMethods 
    { 
        [ConditionMethod("myrandom")] 
        public static int Random(int max) 
        { 
            return new Random().Next(max); 
        } 
    } 
} 

<rules>
    <logger name="*" writeTo="file">
        <filters>
            <when condition="length('${message}') > 100" action="Ignore" />
            <when condition="equals('${logger}','MyApps.SomeClass')" action="Ignore" />
            <when condition="(level >= LogLevel.Debug and contains('${message}','PleaseDontLogThis')) or level==LogLevel.Warn" action="Ignore" />
            <when condition="not starts-with('${message}','PleaseLogThis')" action="Ignore" />
        </filters>
    </logger>
</rules>

ログレベル

以下の６種類（Log4netと同じ）

• off
• Fatal
• Error
• Warn
• Info
• Debug
• Trace