Appender Reference

FilteringAppender

FilteringAppender Overview

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.

FilteringAppender Syntax

XML Configuration

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

<filter-definitions>

</filter>

</layout>

</appender>

FilteringAppender Syntax Description

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

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

Default:	None
Required:	Yes

ref="referenced-appender-name"

specifies the appender that events are to be passed to.

Required:

Yes

filter-definitions

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

Default:	None
Required:	No
Main discussion:	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.

Required:	No
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.
Main discussion:	Pattern Layout

name="Locale" value="locale"

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

Required:	No
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. 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.
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.

Required:	No
Default:	TRUE

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.

Required:	No
Default:	None
See:	Logging Thresholds

FilteringAppender 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>

FilteringAppender Usage and Best Practices

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.

Top of Page