FilteringAppender

Filters events based on thresholds and string values to determine whether the events should be passed to a referenced appender. You can specify a layout to be applied to the events before they are passed.

Valid in:

XML configuration

Table of Contents

Syntax

<appender-ref ref="referenced-appender-name"/>

<filter-definitions>

</filter>

</layout>

</appender>

Syntax Description

class="FilteringAppender" name="appender-name"

specifies the user-assigned name for this instance of FilteringAppender.

Default	None
Requirement	These element attributes are required.

ref="referenced-appender-name"

specifies the appender that events are to be passed to.

Requirement

This element attribute is required.

filter-definitions

specifies the names and associated parameters of filters that limit the messages that are passed to the referenced appender.

Default	None
Requirement	Filters are not required.
See	Filters

name="ConversionPattern" value="conversion-pattern"

specifies formatting that is to be applied to the event before it is passed to the referenced appender. The resulting string becomes the %m portion of the event in the layout of the referenced appender.

Default	None. If a conversion pattern is not specified, then the log message is formatted only by the layout that is specified in the referenced appender.
Requirement	This parameter is not required.
See	Pattern Layouts

name="Locale" value="locale"

specifies the locale that is used when the specified layout is applied to the event.

Default	The locale setting that is in effect for the SAS session. For example, the LOCALE system option might be specified in the configuration file for a SAS server or in the configuration file for Base SAS.
Default	For logging processes that run outside a SAS session (for example, logging for the SAS Object Spawner), the default is the locale that is specified in the operating system settings.
Requirement	This parameter is not required.
See	SAS National Language Support (NLS): Reference Guide

name="PropagateLayout" value="TRUE | FALSE"

specifies whether the layout that is specified in the conversion pattern is to be applied to events before they are passed to the referenced appender. Specify one of the following values:

TRUE: applies the specified layout to events before they are passed to the referenced appender. The resulting string becomes the %m portion of the event in the layout of the referenced appender.

FALSE: passes events to the referenced appender without applying the specified layout. Messages are formatted only by the layout that is specified in the referenced appender.

Default	TRUE
Requirement	This parameter is not required.

specifies the lowest event level that this appender processes. Events that are below the specified level are ignored. The valid values are listed here from lowest to highest.

Default	None
Requirement	This parameter is not required.
See	Logging Thresholds

Details

FilteringAppender enables you to do one or both of the following:

filter events based on thresholds and string values to determine whether the events should be passed to a referenced appender.
apply a layout to events before they are passed to the referenced appender. The resulting string becomes the %m portion of the event in the layout of the referenced appender.

Since FilteringAppender is an intermediate appender rather than a logging destination, it must be configured with an appender reference.

The primary use of FilteringAppender is to specify different layouts for different categories of events that are to appear together in the same log. Specify a separate instance of FilteringAppender for each event category that requires a different layout. After the layout is applied, the resulting string becomes the %m portion of the event in the layout of the referenced appender. You can specify filters to limit the events that are passed.

If you do not specify a layout, or if you set the PropagateLayout parameter to FALSE, then events are formatted only by the layout of the referenced appender.

Example

The following logging configuration file writes two different categories of events to the same log file:

Events from the App.Program logger. These events are written directly to the log file.
Events from loggers other than App.Program, if they contain the word “state.” For these events, a layout is applied that includes the event's level and logger followed by the message. The resulting string becomes the %m portion of the event in the log file's layout.

<?xml version="1.0" encoding="UTF-8"?>
<logging:configuration xmlns:logging="http//support.sas.com/xml/logging/1.0">
   <!-- Write just the message portion of the event to the log file. -->
   <appender name="file" class="FileAppender">
      <param name="Append" value="false" />
      <param name="FileNamePattern" value="logfile.%S{pid}.log" />
      <layout>
         <param name="ConversionPattern" value="%m" />
      </layout>
   </appender>
   <!-- 
      Include only the events that contain the word "state," and 
      prepend the level and the logger name of the event to the
      message.
   -->
   <appender name="filter" class="FilteringAppender">
      <appender-ref ref="file" />
      <filter class="StringMatchFilter">
         <param name="StringToMatch" value="state" />
         <param name="AcceptOnMatch" value="true" />
      </filter>
      <filter class="DenyAllFilter" />
      <layout>
         <param name="ConversionPattern" value="%c - %p - %m" />
      </layout>
   </appender>
   <-- Send App.Program messages directly to the log file -->
   <logger name-"App.Program" additivity="false">
      <appender-ref ref="file" />
      <level value="INFO" />
   </logger>
   <-- 
      Send all other events to the filter so that a different layout
      can be applied.
   ->
   <root>
      <appender-ref ref="filter" />
      <level value="INFO" />
   </root>
   </logging:configuration>