Filter events in the config.

Platforms Supported: All

<rules>
  <logger ... >
    <filters defaultAction="Neutral | Ignore | Log | LogFinal | IgnoreFinal">
      <when condition="Condition" action="Enum"/>
    </filters>
  </logger>
</rules>

• defaultAction - default filter action when no match. Default Ignore.

  Introduced with NLog 4.6. Before NLog 5.0 the default was Neutral.

  • Ignore - The message should not be logged.
  • IgnoreFinal - The message should not be logged and ignore any following logging-rules.
  • Log - The message should be logged.
  • LogFinal - The message should be logged and ignore any following logging-rules.
  • Neutral - No decision

• filterdefaultaction - Alternative name for defaultAction to match actual API.

  Introduced with NLog 5.0

• condition - Condition expression. Condition Required. See section Conditions below.
• action - Action to be taken when filter matches. Required.
  Possible values:
  • Ignore - The message should not be logged.
  • IgnoreFinal - The message should not be logged and ignore any following logging-rules.
  • Log - The message should be logged.
  • LogFinal - The message should be logged and ignore any following logging-rules.
  • Neutral - The filter doesn't want to decide whether to log or discard the message.

Conditions are expressions used with the <when> filter. They consist of one or more tests. They are used in the filter to determine if an action will be taken.

• message - LogEvent formatted message
• logger - Logger name
• level - LogLevel object
• exception - Exception object (Introduced with NLog 5.0)
• ${layout} - All available layout-options (except stacktrace).

The filter expressions are written in a special mini-language. The language consists of:

• relational operators: ==, !=, <, <=, >= and >
  Note: Some predefined XML characters may need to be escaped. For example, if you try to use the '<' character, the XML parser will interpret it as an opening tag which results in an error in the configuration file. Instead, use the escaped version of '<' (<) in this context.
• boolean operators: and, or, not
• string literals which are always evaluated as layouts - ${somerenderer}
• boolean literals - true and false
• numeric literals - e.g. 12345 (integer literal) and 12345.678 (floating point literal)
• log level literals - LogLevel.Trace, LogLevel.Debug, ... LogLevel.Fatal
• predefined keywords to access the most common log event properties - level, message and logger
• braces - to override default priorities and group expressions together
• condition functions - to perform string and object tests
• Single quotes should be escaped with another single quote.

The following condition functions are available:

• contains(s1,s2) Determines whether the second string is a substring of the first one. Returns: true when the second string is a substring of the first string, false otherwise.
• ends-with(s1,s2) Determines whether the second string is a suffix of the first one. Returns: true when the second string is a prefix of the first string, false otherwise.
• equals(o1,o2) Compares two objects for equality. Returns: true when two objects are equal, false otherwise.

  Notice that 'o1' == 'o2' or 'o1' != 'o2' will be faster and reduces memory allocations.

• length(s) Returns the length of a string.

  Notice that 's' != '' is faster than length('s') > 0, and reduces memory allocation.

• starts-with(s1,s2) Determines whether the second string is a prefix of the first one. Returns: true when the second string is a prefix of the first string, false otherwise.
• regex-matches(input, pattern, options) Introduced in NLog 4.5. Indicates whether the regular expression pattern finds a match in the specified input string. options is an optional comma separated list of values from the RegexOptions enumeration.
  Returns : true when a match is found in the input string, false otherwise.
  Example : regex-matches('${message}', '^foo$', 'ignorecase,singleline')

Single quotes should be escaped with another single quote. Example:

contains('${message}', 'Cannot insert the value NULL into column ''Col1')

New custom condition functions methods can also be added.

NLog 4.7 allows you to register your own condition methods using LogFactory.Setup(). Where a lambda can be registered like this:

LogManager.Setup().SetupExtensions(s => 
   s.RegisterConditionMethod("hasParameters", evt => evt.Parameters?.Length > 0)
);

And a static method like this:

LogManager.Setup().SetupExtensions(s =>
   s.RegisterConditionMethod("hasPriority", typeof(NLogConditionMethods).GetMethod("HasPriority", BindingFlags.Static))
);

Alternative way of adding custom condition methods is creating a public static class with a static function and mark the class and method with the attributes [ConditionMethods] and [ConditionMethod] respectively.

You can find a sample implementation of a custom filter here

Then you have to tell NLog where to find your assembly (Ex. NLog.ConditionMethodsAssembly.dll)

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

Here are several examples with conditions:

<rules>
    <logger name="*" minLevel="Debug" writeTo="file">
        <filters defaultAction="Log">
            <when condition="exception != null" action="Log" />
            <when condition="length(message) > 100" action="Ignore" />
            <when condition="'${OnHasProperties:1}' != ''" action="Ignore" />
            <when condition="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" />
            <when condition="contains(message, '&quot;Bob&quot;')" action="Ignore" />  <!-- "Bob" -->
        </filters>
    </logger>
</rules>