Ukadc.Diagnostics.Filters.PropertyFilter
Description
The property filter is a TraceFilter that can be used to filter events by comparing specified values with the values of various log event properties. This is best described with an example.
Example Usage
For example, using the property filter you could filter all events that occur before a certain time using the {DateTime} token. In this configuration snippet we're configuring a standard TraceSource and Listener and adding a PropertyFilter from the Ukadc.Diagnostics library.
<source name="mySource" switchValue="All">
<listeners>
<add type="System.Diagnostics.ConsoleTraceListener" name="inMemoryListener">
<filter type="Ukadc.Diagnostics.Filters.PropertyFilter, Ukadc.Diagnostics" initializeData="myPropertyFilter"/>
</add>
</listeners>
</source>
Because the PropertyFilter requires more information than can be contained within the initializeData attribute this value ("myPropertyFilter" in the example above) is a reference to additional configuration in the ukadc.diagnostics configuration section.
<ukadc.diagnostics>
<propertyFilters>
<propertyFilter name="myPropertyFilter" propertyToken="{Message}" operation="Contains" value="Server Failed"/>
</propertyFilters>
</ukadc.diagnostics>
In the example configuration above, the property filter would remove (filter) all messags that
don't contain the string "Server Failed", thus only strings containing that value would reach the listener (remember, this could be used in conjunction with the
MultiFilters Negate feature).
Tokens
The
propertyToken attribute can be specified as any valid token. For more information see
Tokens.
Operations
The operation attribute specifies the nature of the comparison agains the value attribute. The following list of operations are valid. However, the operations that can be used depend on the Type of the token (e.g. {Message} = String). Operations can work against two primary types: Strings and any type that implements IComparable (most primitives in .NET implement IComparable: enums, int, long, DateTime etc).
- Equals - String and IComparable
- NotEquals - String and IComparable
- IsNull - String only
- IsNotNull - String only
- Contains - String only
- StartsWith - String only
- EndsWith - String only
- GreaterThan - IComparable Only
- GreaterThanOrEqualTo - IComparable Only
- LessThan - IComparable Only
- LessThanOrEqualTo - IComparable Only
Example using DateTime token and MultiFilter
<ukadc.diagnostics>
<propertyFilters>
<propertyFilter name="myPropertyFilter" propertyToken="{DateTime}" operation="GreaterThanOrEqualTo" value="2008-10-31 12:00"/>
</propertyFilters>
</ukadc.diagnostics>
This filter would now remove any events occuring before midday on 31 October 2008. Events on or after this date would be allowed through. You can imagine extending this scenario using the
MultiFilter to allow events to reach a specific listener during a specific window in time. For example, if you had a recurring issue and wanted to write all log events to the database between 2am and 4am on a specific date:
<ukadc.diagnostics>
<filterGroups>
<filterGroup name="myGroup" logic="And">
<filters>
<filter name="filterA" type="Ukadc.Diagnostics.Filters.PropertyFilter, Ukadc.Diagnostics" initializeData="propertyFilter1" />
<filter name="filterB" type="Ukadc.Diagnostics.Filters.PropertyFilter, Ukadc.Diagnostics" initializeData="propertyFilter2" />
</filters>
</filterGroup>
</filterGroups>
<propertyFilters>
<propertyFilter name="propertyFilter1" propertyToken="{DateTime}" operation="GreaterThanOrEqualTo" value="2008-10-31 02:00"/>
<propertyFilter name="propertyFilter2" propertyToken="{DateTime}" operation="LessThanOrEqualTo" value="2008-10-31 04:00"/>
</propertyFilters>
</ukadc.diagnostics>
Dynamic Properties
It is possible for developers to log objects (or even an array of objects) of any type to the System.Diagnostics plumbing using either of these methods (members of TraceSource):
public void TraceData(TraceEventType eventType, int id, object data);
public void TraceData(TraceEventType eventType, int id, params object[] data);
You can configure a PropertyFilter to evaluate properties on any type of object (or array of objects) passed as the data parameter. For example, in this configuration snippet we are specifying that we want to filter log events if the data object is of type
YourNamespace.YourClass and its
YourClassProperty does not contain "some value".
<propertyFilter name="myPropertyFilterRef" operation="Contains" value="some value">
<dynamicProperty sourceType="YourNamespace.YourClass, YourAssembly" propertyName="YourClassProperty" />
</propertyFilter>
Note, if you pass an array of objects, the PropertyFilter will loop through each item in the object array looking for an object of the appropriate type (note, once a matching type has been found the filter does not continue to loop through any remaining items).
If the object is
not of type
YourNamespace.YourClass then the PropertyFilter will fallback to returning the
default evaluation. The
default value of defaultEvaluation is true (that is, if no matching object is found the PropertyFilter will
not filter the event). You can change the
defaultEvaluation using the appropriate attribute:
<propertyFilter name="myPropertyFilterRef" operation="Contains" value="some value" defaultEvaluation="false">
<dynamicProperty sourceType="YourNamespace.YourClass, YourAssembly" propertyName="YourClassProperty" />
</propertyFilter>
In this instance the filter will remove all log events where the array of data objects does not contain a type of
YourNamespace.YourClass and will only allow log events through where the
YourClassProperty satisfies the 'Contains "some value"' evaluation.
Note: It is invalid to specify a propertyToken value on the propertyFilter element
and a dynamicProperty element. Doing so will result in a ConfigurationErrorsException the first time the filter is used.