Writes log messages to one or more files.
Since NLog 4.3 the ${basedir} isn't needed anymore for relative paths.
Supported in .NET, Silverlight, Compact Framework and Mono.
Configuration Syntax
<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"
enableArchiveFileCompression="Boolean"
cleanupFileName="Boolean" />
</targets>
Read more about using the Configuration File.
Parameters
General Options
name - Name of the target.
forceManaged - Indicates that the file target should only use managed methods. This disables some of the options.
Layout Options
layout - Text to be rendered. Layout Required. Default:${longdate}|${level:uppercase=true}|${logger}|${message}
header - Header. Layout
footer - Footer. Layout
encoding - File encoding name like "utf-8", "ascii" or "utf-16". See Encoding class on MSDN. Defaults to Encoding.Default (UTF-8 on silverlight)
lineEnding - Line ending mode. Possible values:
- CR - Insert CR character (ASCII 13) after each line.
- CRLF - Insert CR LF sequence (ASCII 13, ASCII 10) after each line.
- Default - Insert platform-dependent end-of-line sequence after each line.
- LF - Insert LF character (ASCII 10) after each line.
- None - Don't insert any line ending.
Archival Options
archiveAboveSize - Size in bytes above which log files will be automatically archived. Long Caution: Enabling this option can considerably slow down your file logging in multi-process scenarios. If only one process is going to be writing to the file, consider setting ConcurrentWrites to false for maximum performance. *Warning: combining this mode with Archive Numbering Date is not supported. Archive files are not merged. _ DateAndSequence_ do will work. *
maxArchiveFiles - Maximum number of archive files that should be kept. Integer Default: 9
archiveFileName - Name of the file to be used for an archive. Layout It may contain a special placeholder {#####} that will be replaced with a sequence of numbers depending on the archiving strategy. The number of hash characters used determines the number of numerical digits to be used for numbering files.
archiveNumbering - Way file archives are numbered. Possible values:
- Rolling - Rolling style numbering (the most recent is always #0 then #1, ..., #N).
- Sequence - Sequence style numbering. The most recent archive has the highest number.
- Date - Date style numbering. The date is formatted according to the value of archiveDateFormat. *Warning: combining this mode with archiveAboveSize is not supported. Archive files are not merged. *
- DateAndSequence - Combination of Date and Sequence .Archives will be stamped with the prior period (Year, Month, Day) datetime. The most recent archive has the highest number (in combination with the date). The date is formatted according to the value of archiveDateFormat.
See Archive Numbering Examples
archiveEvery - Indicates whether to automatically archive log files every time the specified time passes. Possible values:
- Day - Archive daily.
- Hour - Archive every hour.
- Minute - Archive every minute.
- Month - Archive every month.
- None - Don't archive based on time.
- Year - Archive every year.
Files are moved to the archive as part of the write operation if the current period of time changes. For example if the current hour changes from 10 to 11, the first write that will occur on or after 11:00 will trigger the archiving. Caution: Enabling this option can considerably slow down your file logging in multi-process scenarios. If only one process is going to be writing to the file, consider setting ConcurrentWrites to false for maximum performance.
archiveDateFormat - Specifies the date format used for archive numbering. Default format depends on the archive period.
This option works only when the "ArchiveNumbering" parameter is set to Date
Output Options
replaceFileContentsOnEachWrite - Indicates whether to replace file contents on each write instead of appending log message at the end. Boolean Default: False
fileAttributes - File attributes (Windows only). Possible values:
- Archive - File should be archived.
Compressed- Compress won't work due to .Net restrictions. You can use enableArchiveFileCompression.- DeleteOnClose - Delete file after it is closed.
- Device - Device file.
- Encrypted - Encrypted file.
- Hidden - Hidden file.
- NoBuffering - The system opens a file with no system caching.
- Normal - Normal file.
- NotContentIndexed - File should not be indexed by the content indexing service.
- PosixSemantics - A file is accessed according to POSIX rules.
- Readonly - Read-only
- ReadOnly - Read-only file.
- ReparsePoint - Reparse point.
- SparseFile - Sparse file.
- System - System file.
- 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: > * Silverlight 4.0
fileName - Name of the file to write to. Layout Required. This FileName string is a layout which may include instances of layout renderers. This lets you use a single target to write to multiple files. The following value makes NLog write logging events to files based on the log level in the directory where the application runs. ${basedir}/${level}.log All Debug messages will go to Debug.log, all Info messages will go to Info.log and so on. You can combine as many of the layout renderers as you want to produce an arbitrary log file name. Since NLog 4.3 the ${basedir} isn't needed anymore for relative paths.
deleteOldFileOnStartup - Indicates whether to delete old log file on startup. Boolean Default: False This option works only when the "FileName" parameter denotes a single file.
enableFileDelete - Indicates whether to enable log file(s) to be deleted. Boolean Default: True
createDirs - Indicates whether to create directories if they don't exist. Boolean Default: True Setting this to false may improve performance a bit, but you'll receive an error when attempting to write to a directory that's not present.
enableArchiveFileCompression - Indicates whether to compress the archive files into the zip files.Boolean Default: False > Supported in: > * NLog v4.0 for .NET 4.5
Performance Tuning Options
concurrentWrites - Indicates whether concurrent writes to the log file by multiple processes on the same host. Boolean Default: True This makes multi-process logging possible. NLog uses a special technique that lets it keep the files open for writing. NOTE: are ignored unless keepFileOpen are set to true.
openFileCacheTimeout - Maximum number of seconds that files are kept open. If this number is negative the files are not automatically closed after a period of inactivity. Integer Default: -1
openFileCacheSize - Number of files to be kept open. Setting this to a higher value may improve performance in a situation where a single File target is writing to many files (such as splitting by level or by logger). Integer Default: 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 - Indicates whether concurrent writes to the log file by multiple processes on different network hosts. Boolean Default: 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
cleanupFileName - before writing to a file, the name of the file get checked for illegal characters (OS dependent). This can be costly if a lot of messages are written. The cleanup is cached for fixed names (no layout renderers). Set this to false for optimal performance (but beware of the file name, if it's wrong, nothing gets written). Default: true. Introduced in NLog 4.2.3.
bufferSize - Log file buffer size in bytes. Integer Default: 32768
autoFlush - Indicates whether to automatically flush the file buffers after each log message. BooleanDefault: True
keepFileOpen - Indicates whether to keep log file open instead of opening and closing it on each logging event. Boolean Default: False Setting this property to True helps improve performance.
Examples
Simple logging
The simplest use of File target is to produce single log file. In order to do this, put the following code in the configuration file such as NLog.config. Logs wil be written to logfile.txt in logs directory.
<?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>
Per-level log files
Single File target can be used to write to multiple files at once. The following configuration will cause log entries for each log level to be written to a separate file, so you will get:
- 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>
One log file per day
The following configuration will create one log file for each day. Log files will be named:
- 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>
Asynchronous logging
Depending on your usage scenario it may be useful to add an AsyncWrapper target the file target. This way all your log messages will be written on a separate thread so your main thread can be unblocked more quickly. Asynchronous logging is recommended for multi-threaded server applications which run for a long time and is not recommended for quickly-finishing command line applications.
<?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>
Creating comma-separated log file (CSV)
In order to create comma-separated files (CSV), use the following configuration, which utilizes CsvLayout. The resulting file will have 4 columns and will be formatted according to CSV rules:
<?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>
Size-based file archival
Log files can be automatically archived by moving them to another location after reaching certain size. The following configuration will create logs/logfile.txt which will be archived to archives/log.000000.txt', archives/log.000001.txt', archives/log.000002.txt' and so on once the main log file reaches 10KB.
<?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>
Time-based file archival
Log files can calso be automatically archived based on time. This configuration will archive a file at the beginning of each day and will use rolling file naming, so log file from the previous day can always be found in archives//log.0.txt, log from two days ago is in archives//log.1.txt and so on. This configuration will keep at most 7 archive files, so logs older than one week will be automatically deleted.
<?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>
Archive Numbering Examples
Rolling
<target name="file" xsi:type="File"
...
archiveFileName="log.{####}.txt"
archiveNumbering="Rolling" />
Example archive file names:
- log.0000.txt
- log.0001.txt
- log.0002.txt
Sequence
<target name="file" xsi:type="File"
...
archiveFileName="log.{####}.txt"
archiveNumbering="Sequence" />
Example archive file names:
- log.0000.txt
- log.0001.txt
- log.0002.txt
Date
<target name="file" xsi:type="File"
...
archiveFileName="log.{#}.txt"
archiveNumbering="Date"
archiveEvery="Day"
archiveDateFormat="yyyyMMdd"
/>
Example archive file names:
- log.20150730.txt
- log.20150731.txt
DateAndSequence
<target name="file" xsi:type="File"
...
archiveFileName="log.{#}.txt"
archiveNumbering="DateAndSequence"
archiveAboveSize="1000"
archiveDateFormat="yyyyMMdd"
/>
Example archive file names:
- log.20150730.1.txt
- log.20150730.2.txt
- log.20150730.3.txt