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.

Last edited Mar 25, 2008 at 7:59 AM by joshtwist, version 13

Comments

No comments yet.