NLog之：文件類型目標（File target）

英文原文[http://nlog-project.org/wiki/File_target]

用途

將日志信息寫到一個或多個文件中。

支持.NET Framework1.0; 1.1; 2.0; 3.5; 4.0 SilverLight4.0 .NET Compact Framework1.0; 2.0; 3.5; Mono.NET.

配置語法

<targets>
  <target xsi:type="File"
          name="String"
          layout="Layout"
          header="Layout"
          footer="Layout"
          encoding="Encoding"
          lineEnding="Enum"
          archiveAboveSize="Long"
          maxArchiveFiles="Integer"
          archiveFileName="Layout"
          archiveNumbering="Enum"
          archiveEvery="Enum"
          replaceFileContentsOnEachWrite="Boolean"
          fileAttributes="Enum"
          fileName="Layout"
          deleteOldFileOnStartup="Boolean"
          enableFileDelete="Boolean"
          createDirs="Boolean"
          concurrentWrites="Boolean"
          openFileCacheTimeout="Integer"
          openFileCacheSize="Integer"
          networkWrites="Boolean"
          concurrentWriteAttemptDelay="Integer"
          concurrentWriteAttempts="Integer"
          bufferSize="Integer"
          autoFlush="Boolean"
          keepFileOpen="Boolean" />
</targets>

更多配置文件使用方法。

參數

常規選項

 name – target節點名稱

布局選項

 layout – 日志呈現的文本內容。默認為：

 ${longdate}|${level:uppercase=true}|${logger}|${message}

 header – 日志頭顯示的文本內容。

 footer – 日志尾顯示的文本內容。

 encoding – 文件編碼方式。

 lineEnding – 行結束模式。

可選值：

•   CR – 在每尾部插入回車符號（ASCII 13）。
•   CRLF – 在每行尾部插入回車和換行符號（ASCII 13 & ASCII 10）。
•   Default – 在每行尾部插入平台相關的行結束符號（默認）。
•   LF - 在每行尾部插入換行符號（ASCII 10）。
•   None – 不插入任何行結束符號。

文件存檔選項

archiveAboveSize – 存檔上限值。當日志文件大於此值是，將自動存檔。其類型為Long。

注意：在多進程並發記錄日志的情況下，啟用該選項可能會大幅降低日志記錄速度。在單進程時，為了達到最佳性能，可以考慮設置ConcurrentWrites為false。

maxArchiveFiles – 保存的最大存檔文件數。其類型類Integer，默認為9個。

archiveFileName – 存檔文件名稱。允許使用Layout。

備注：此文件名稱中可能包含特殊占位符{#####}，它將根據存檔策略，由一個數字序列替代，其中占位符的個數決定了文件名稱中的數字。

archiveNumbering – 存檔文件的編號方式。

可選值：

Rolling – 滾動式編號，即最新的日志文件編號為0，然后是1，… ，N。

• Sequence – 序列式編號，即最大編號的日志文件為最新的日志文件。

archiveEvery – 是否在每個設定時間刻自動存檔日志文件。

可選值：

• Day – 每日存檔。
• Hour – 每小時存檔。
• Minute – 每分鍾存檔。
• Month – 每月存檔。
• None – 不按時間固定存檔。
• Year – 每年存檔。

備注：作為寫日志的一部分，文件移動到存檔位置的操作發生的時間變換時刻。例如，當前時間從10點變至11點，則當在寫第11點或11點之后的第一個寫操作時，觸發日志文件歸  檔。

注意：在多進程並發記錄日志的情況下，啟用該選項可能會大幅降低日志記錄速度。在單進程時，為了達到最佳性能，可以考慮設置ConcurrentWrites為false。

輸出選項

replaceFileContentsOnEachWrite – 是否覆蓋每次寫入的日志內容，而不是在文件后面追加。其取值類型為Boolean，默認為false。

fileAttributes – 文件屬性（只支持Windows）。

可選值：

Archive – 歸檔文件。

Compressed – 此文件是壓縮文件。

DeleteOnClose – 文件關閉后刪除。

Device – 設備文件（MSDN中為：保留供將來使用）。

Encrypted – 加密文件。

Hidden – 隱藏文件。

NoBuffering –文件打開時不使用系統緩存 。

Normal - 文件正常，沒有設置其他的特性。

NotContentIndexed – 將不會通過操作系統的內容索引服務來索引此文件。

PosixSemantics – 按照POSIX規則存取的文件。

ReadOnly – 只讀。

ReparsePoint – 重(新)分析點^[1]。

SparseFile – 稀疏文件。

System – 系統文件。

Temporary – 臨時文件（盡可能的保存在緩存中，但是不會寫入磁盤）。

WriteThrough – 系統通過任何中間緩存后再直接寫入磁盤中。

    此參數在以下平台中不支持：

    NLog v1.0 for .NET Compact Framework 1.0

    NLog v1.0 for .NET Compact Framework 2.0

    NLog v2.0 for .NET Compact Framework 2.0

    NLog v2.0 for .NET Compact Framework 3.5

    NLog v2.0 for Silverlight 4.0

 filename – 寫入日志的文件名稱。支持Layout。

備注：文件名字符串中可能包含布局呈現器中的實例變量。這樣可以通過配置單個目標節點，而將日志寫入多個文件中。

以下fileName屬性值將使得NLog在應用程序啟動目錄下，根據日志級別不同，將日志信息寫到不同的文件中。

${basedir}/${level}.log

因此，所有的Debug級別日志寫入到Debug.log文件中，所有的Info級別日志寫入到Info.log文件中，其它以此類推。同時，也可以結合其它布局呈現器實例，組成所要的日志文件名稱。

 deleteOldFileOnStartUp – 啟動時，是否刪除舊的日志文件。其取值類型為Boolean，默認為false。

備注：此選項，僅在“fileName”參數為單個文件時有效。

 enableFileDelete – 是否允許刪除日志文件。其取值類型為Boolean，默認為true。

 createDirs – 是否允許自動創建（不存在的）目錄。其取值類型為Boolean，默認為true。

備注：設置此屬性為false或許會對性能有那么一丁點的改善，但是如果目錄不存在，則會在試圖寫入日志時報錯。

性能優化選項

 concurrentWirtes – 是否允許使用通過多個進程的方式，將日志信息並行寫入文件中。其取值類型為Boolean，默認為true。

備注：這使得多進程記錄日志成為可能。NLog使用一種特別的技術使用文件保持打開狀態以備寫入。

 openFileCacheTimeout – 文件保持打開狀態的最大時間秒數。如果這個數字為負數，則在一定不活動時間后，文件不會自動關閉。其取值類型為Integer，默認值為-1。（即默 認狀態下文件始終處於打開狀態以備寫入。）

openFileCacheSize – 保持打開狀態的文件數量。當通過設置單個文件類型目標，且結果寫入多個不同文件（如根據日志等級或日志對象名稱）時，則可將此屬性設置為一個較 高的值以改善性能。其取值類型為Integer，默認值為5。

備注：這些文件是在最近最少使用算法基礎管理的，此算法在緩存空間不足時將最長時間內沒有使用的文件Flush。一般來說，不應當把此參數設置過大，最好不要超過10-15，這是因同時保持多個文件處於打開狀態，對系統資源來說是一個很大的消耗。

networkWrites – 是否通過多線程由不同的網絡主機並行向文件中寫入日志。其取值類型為Boolean，默認值為false。

備注：通過此此種方式，可以有效阻止文件長期保存為打開狀態。

concurrentWriteAttemptDelay – 在再次嘗試將日志寫入文件之前延遲的毫秒數。其取值類型為Integer，默認值為1。

備注：實際的延遲時間，是一個介於0到指定參數值之間的隨機整數，且在每次嘗試失敗之后，都會將此參數加倍。假使此參數值為10，則第一次重試寫入的延遲時間（毫秒數）在 0-10之間的一個隨機數，第二次重試時為0-20之間的一個隨機數，第三次重試時為0-40之間的一個隨機數，第四次重試時為0-80之間的一個隨機數等等，以此類推。

concurrentWriteAttempts – 在NLog丟棄日志信息之前的追加（嘗試重寫）寫次數。其取值類型為Integer，默認值為10。

bufferSize – 日志文件緩存區大小（單位：字節）。其取值類型為Integer，默認值為32768（32KB）。

autoFlush – 在每次日志信息后，是否自動刷新文件緩存區。其取值類型為Boolean，默認值為true。

keepFileOpen – 是否保持日志文件處於打開狀態，以代替其在每次日志寫事件發生時頻繁打開和關閉。其取值類型為Boolean，默認值為false。

備注：設置此屬性為true，有助於提高性能。

 

---

 

配置示例

簡單日志記錄

下面是一個非常簡單的文件類型目標示例，它將生成單個日志文件，為此需要將以下代碼放到NLog.config此類的配置文件中，程序日志將被寫入到應用程序目錄下的logs/logfile.txt文件中。

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

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

分級別日志記錄文件

單個文件類型目標也可以將日志寫入多個文件中，下面的配置將促使每個級別的日志信息寫入單獨的文件中，因此你將看到有以下文件：

Trace.log

Debug.log

Info.log

Warn.log

Error.log

Fatal.log

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

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/${level}.log" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

每天生成一個日志文件

下面的配置將每天產生一個日志文件，並且將按以下命名方式命名：

2010-06-05.log

2010-06-06.log

2010-06-07.log

2010-06-08.log

……

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

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/${shortdate}.log" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

異步日志記錄

根據使用場景，可以為文件類型目標增加異步包裝器屬性，通過此種方法可以使用獨立的線程記錄日志信息，從而防止主線程被阻塞且更快的執行。推薦在多線程的服務器應用程序中使用異步日志記錄功能，而在執行時間不長的命令行程序中則沒有必要使用此方法。

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

    <targets>
        <!-- Log in a separate thread, possibly queueing up to
        5000 messages. When the queue overflows, discard any
        extra messages-->

        <target name="file" xsi:type="AsyncWrapper" queueLimit="5000" overflowAction="Discard">
            <target xsi:type="File" fileName="${basedir}/logs/${level}.txt" />
        </target>
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

創建以逗號隔開的日志文件（CSV格式）

為了創建CSV格式文件，可以使用以下配置，它利用了CsvLayout。以下示例將創建一個含有4列並被格式化為CSV格式的日志文件。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <targets>
        <target name="csv" xsi:type="File" fileName="${basedir}/file.csv">
            <layout xsi:type="CSVLayout">
                <column name="time" layout="${longdate}" />
                <column name="message" layout="${message}" />
                <column name="logger" layout="${logger}"/>
                <column name="level" layout="${level}"/>
            </layout>
        </target>
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="csv" />
    </rules>
</nlog>

按大小將文件存檔

日志文件達到一定大小之后，將移動到指定的其它位置以存檔。下面的配置將創建logs/logfile.txt，並當此文件大小達到10KB時，將日志內容移動至archives/log.000000.txt, archives/log.000001.txt, archives/log.000002.txt等（並且默認只保留最后的9個存檔文件）。

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

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            archiveFileName="${basedir}/archives/log.{#####}.txt"
            archiveAboveSize="10240"
            archiveNumbering="Sequence"
            concurrentWrites="true"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

按時間將文件存檔

日志文件也可以基於時間設置自動存檔。下面的配置將在每天的開始時刻里將日志文件存檔，並且使用滾動文件命名方式。因此，前一天的日志可以在文件archives/log.0.txt文件中找到，再前一天的數據可以在archives/log.1.txt文件中找到，以此類推。此配置將保存最近的7個存檔文件，因此，早於當前時間一周前的日志數據將被刪除。

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

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            archiveFileName="${basedir}/archives/log.{#}.txt"
            archiveEvery="Day"
            archiveNumbering="Rolling"
            maxArchiveFiles="7"
            concurrentWrites="true"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

[1] http://msdn.microsoft.com/zh-cn/library/aa365503(v=VS.85).aspx

Technorati 標簽: NLog 日志管理