File target
将日志写入一个或者多个文本文件
语法
<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" forceManaged="Boolean" /></targets> |
参数
一般配置
name - target的名称
forceManaged - 是否只使用受管理的方法。这个配置会禁用一些其他的配置。
布局配置
layout - 日志文本的输出配置。默认： ${longdate}|${level:uppercase=true}|${logger}|${message}
header - 输出日志的页头
footer - 输出日志的页尾
encoding - 文件编码
lineEnding - 行结尾标识
可能的值
- CR - 在每行的末尾插入CR字符(ASCII 13)。
- CRLF - 在每行末尾插入 CR LF 序列 (ASCII 13, ASCII 10)。
- Default - 在每行末尾插入平台默认的字符串结束符
- LF - 在每行末尾插入 LF 字符(ASCII 10)。
- None - 不要插入任何字符
归档配置
archiveAboveSize - 设置日志文件超过多大时，会自动归档
小心： 这个配置会影响多线程下的日志写入。如果只有一个线程，可以将ConcurrentWrites 设置为false，以提高性能。
maxArchiveFiles - 归档文件可以存在的数量。默认：9
archiveFileName - 归档文件的命名。
比如，我们可以定义一个策略，在文件名和自增序列中间加一个特定的占位符（log##1.txt,log##2.txt）。
archiveNumbering - 归档文件的序号生成规则
可能的值
- Rolling - 循环序列，和maxArchiveFiles 配置有关
- Sequence - 自增序列。
- Date - 日期格式。
archiveEvery - 是否在特定的时间归档
可能的值：
- Day - 每天归档
- Hour - 每小时归档
- Minute - 每分钟归档
- Month - 每月归档
- None - 不归档
- Year - 每年归档
小心： 这个配置会影响多线程下的日志写入。如果只有一个线程，可以将ConcurrentWrites 设置为false，以提高性能。
archiveDateFormat - 归档时间格式，当archiveNumbering 设置为“Date”时有效。
输出配置
replaceFileContentsOnEachWrite - 是否每次都重写日志文件，替换原有的输出到现有日志的末尾。默认：false
fileAttributes - 文件特性(Windows下有用).
可能的值：
- Archive - 文件将被归档
- Compressed - 文件将被压缩
- DeleteOnClose - 关闭时删除
- Device - Device file.
- Encrypted - 加密文件
- Hidden - 隐藏文件
- NoBuffering - 不要使用系统缓存打开文件
- Normal - 一般的文件
- NotContentIndexed - File should not be indexed by the content indexing service.
- PosixSemantics - A file is accessed according to POSIX rules.
-
Readonly - 只读文件
This parameter is not supported in:
- NLog v2.0 for .NET Framework 2.0
- NLog v2.0 for .NET Framework 3.5
- NLog v2.0 for .NET Framework 4.0
- NLog v2.0 for Mono 2.x
-
ReadOnly - 只读文件
This parameter is not supported in:
- NLog v1.0 for .NET Framework 1.0
- NLog v1.0 for .NET Framework 1.1
- NLog v1.0 for .NET Framework 2.0
-
ReparsePoint - Reparse point.
- SparseFile - Sparse file.
- System - 系统文件
- Temporary - File is temporary (should be kept in cache and not written to disk if possible).
- WriteThrough - The system writes through any intermediate cache and goes directly to disk. > This parameter is not supported in: > * 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语法来定义。这个可以实现一个配置，输出到不同的文件。
比如，你可以实现，各种不同等级的日志，输出到不同的文件。你将该参数配置为${basedir}/${level}，那么，Debug日志会输出到Debug.log文件，Info日志会输出到Info.log文件。 你能够使用layout语法生成你想要的文件名称
deleteOldFileOnStartup - 是否在程序启动的时候，删除老的日志文件。默认：false
这个配置在"FileName" 参数是一个单文件的时候，有效
enableFileDelete - 是否可以删除日志文件。默认：True
createDirs - 是否可以创建文件夹。默认：True
设置为false，可以提高提高一点性能，但是，如果没有文件夹，那么将会产生错误。
性能调试配置
concurrentWrites - 是否并发写入日志文件。默认：True
这个配置使得多线程日志成为可能。NLog使用了特有的技术来实现文件保持开启，用以写入
NOTE: keepFileOpen 设置为ture时才有用
openFileCacheTimeout - 文件保持开启的时间（单位秒）。如果设置为负数，那么不会自动关闭文件。默认：-1。
openFileCacheSize - 保持开启的文件数量。 在一个Target写入多个文件时，将这个值设置大点，能提高性能。默认：5
The files are managed on a LRU (least recently used) basis, which flushes the files that have not been used for the longest period of time should the cache become full. As a rule of thumb, you shouldn't set this parameter to a very high value. A number like 10-15 shouldn't be exceeded, because you'd be keeping a large number of files open which consumes system resources.
networkWrites - 不同网络主机是否可以并行写入日志文件。默认：false
This effectively prevents files from being kept open.
concurrentWriteAttemptDelay - Delay in milliseconds to wait before attempting to write to the file again. Integer Default: 1
The actual delay is a random value between 0 and the value specified in this parameter. On each failed attempt the delay base is doubled up to ConcurrentWriteAttempts times.
Assuming that ConcurrentWriteAttemptDelay is 10 the time to wait will be: a random value between 0 and 10 milliseconds - 1st attempt a random value between 0 and 20 milliseconds - 2nd attempt a random value between 0 and 40 milliseconds - 3rd attempt a random value between 0 and 80 milliseconds - 4th attempt ... and so on.
concurrentWriteAttempts - Number of times the write is appended on the file before NLog discards the log message. Integer Default: 10
bufferSize - 日志文件缓存大小（单位bytes）。默认： 32768
autoFlush - 是否在每次日志输出后都自动刷新缓冲区。默认：True
keepFileOpen - 是否保持文件打开。默认：false
设置为true能够提高性能
例子
简单的日志
这个例子使用了一个target，来生成一个单日志文件。
<?xml version="1.0" ?> <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> |
Per-level log files
一个target输出多个日志文件。我们把不同等级的日志，输出到不同的日志文件：
- Trace.log
- Debug.log
- Info.log
- Warn.log
- Error.log
- Fatal.log
<?xml version="1.0" ?> <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" ?> <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> |
异步日志
我们可以再target外出，在加一个AsyncWrapper来实现。这种方式，会将日志操作写入一个特定的线程，这样就不会对主线程产生影响。异步日志建议在多线程及日志需要大量耗时时使用，如果耗时很低，不建议使用。
<?xml version="1.0" ?> <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日志文件，使用下面的配置。
<?xml version="1.0" ?> <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> |
基于文件大小的归档
日志文件在达到配置大小的时候，能够自动归档到特定的目录。下面的配置，实现了将日志归档到： archives/log.000000.txt', archives/log.000001.txt', archives/log.000002.txt' ，每10KB归档。
<?xml version="1.0" ?> <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" ?> <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> |
