Result Publisher Filters

Result Publisher Filters provide fine control over which HealthCheck results are published - this allows you to tune your Wolfpack system to your specific notification requirements. Wolfpack provides two options for controlling the result output of a HealthCheck...
  1. A check may implement it's own filter - this stops results at the source. Examples of this include the SqlScalar and the UrlPing HealthCheck which have a "PublishOnlyIfFailure" configuration setting. However a filter here may be too restrictive - you might want to send the result to one publisher but not another so...
  2. A Result Publisher Filter can be used - these are filters attached to the publisher end of the notification workflow; you can attach a filter to each enabled publisher to independently inspect and decide whether that specific publisher should actually publish the result emitted by the health check(s).
    • eg: You have a UrlPing check running and want to record the response time so you configure the SQLite publisher and store these results in a SQLite database. You also want to be notified if a UrlPing fails so you enable the Growl publisher; Growl popups then start appearing all the time for successful pings too...not what we wanted! So we can attach a filter to target the UrlPing check and the Growl publisher combination - when it receives a "success" result it just throws it away - only "failure" results are forwarded onto the Growl publisher.
Result Publisher Filters work using method interception, they decide whether they should intercept the call to publish a result by examining their configuration and then comparing it to the result and publisher being invoked - if the filter should be applied it will execute its logic to decide whether the Publisher should be called or not.

Result Publisher Filters sit between Wolfpack and it's Publishers and because Wolfpack architecture is consistent when an Agent is running remotely or locally (eg: in a distributed layout with many remote Agents publishing result data to a central "server" Agent or just as a single Agent running HealthChecks) it means that Filters can be applied exactly the same. In the distributed layout each remote Agent can have Filters to ensure that it transmits only the correct data and more Filters can be applied to the "server" Agent to then fine control the Publishers that it then invokes.

NOTE You can create as many filters as you like, they will all fire when a result message is published (although order is undefined as the moment). If there are multiple filters that apply to the same publisher or check then they essentially are all "voting" on whether to publish the result - if any one Filter "votes" no then the Result is discarded regardless of how many other Filters "vote" yes.

Example

To use the built-in Wolfpack Core "SuccessFilter" as an example - this filter examines the "result" property (bool, true/false) of a Wolfpack HealthCheck Result message to decide whether to publish it based on it's configuration. All Filter configuration should be found in the config\filter.castle.config file. It has four configuration properties, two that are common to all Filters and two specific to this Filter; these are...
  • Common properties. These belong on ALL Filters and allow you target different Publisher/HealthCheck combinations
    • Publisher - Use * to attach to all Publishers or provide the "FriendlyId" name of a specific Publisher. The "FriendlyId" can be found in the publisher.castle.config file against each Publisher.
    • Check - Use * to attach to all HealthChecks or provide the "FriendlyId" name of a specific HealthCheck. The "FriendlyId" can be found in the check.castle.config file against each HealthCheck.
  • Specific properties - these are custom properties found only on this specific Filter.
    • PublishSuccess - if a HealthCheck result is "true" (pass) and you wish to publish this then set this property to "true". In many cases though you will want to suppress the publication of a successful HealthCheck - often you are only interested in the failures so set this to false.
    • PublishFailure - if a HealthCheck result is "false" (fail) and you wish to publish this then set this property to "true". In the majority of cases you will want to set this to "true" so that failures are published and you are notified of them.

Configuration Examples

In all cases please uncomment the "ResultFilter" component in the config\filter.castle.config file.
  • You don't want to publish ANY successful HealthCheck results - you are only interested in Failures
    • Set the Publisher property to "*"
    • Set the Check property to "*"
    • Set the PublishSuccess property to "false"
    • Set the PublishFailure property to "true"
  • You want to publish ALL HealthCheck results to the SQLite publisher but don't want sucessful HealthCheck results to be sent to Growl - you only want to be notified of "failures" via Growl.
    • Set the Publisher property to "Growl"
    • Set the Check property to "*"
    • Set the PublishSuccess property to "false"
    • Set the PublishFailure property to "true"

Custom Filters

You can easily create your own Filters to encapsulate your custom logic to decide whether a result should be published. Your Filter has access to the full HealthCheckResult entity that is attempting to be published along with the Publisher instance being invoked (remember the Filter will be invoked for all publisher/check combinations that it applies to).
  1. Create a new class and make sure you have a reference to the Wolfpack.Core assembly.
  2. Inherit from Wolfpack.Core.Filters.ResultFilterBase
  3. Implement the "ShouldPublish" method. This method is called by the base class and passes the HealthCheck Result and the Publisher instance. This should hold your custom logic to inspect the Result and decide whether it should publish it or abort (throw away the result); simply return "true" to publish or "false" to abort.
  4. Add a public property for any behaviour you want to configure on the Filter - these values can then be set in the configuration file.
  5. Register your custom Filter in the configuration file.
    1. In config\filter.castle.config create a new "component" and give it a new unique "id" attribute value. The easiest way is to copy the "ResultFilter" component as a template or use the one below.
    2. Set the "type=" to the fully qualified class name of your new Filter and remember to set the correct assemble name (this is the bit after the comma)
    3. If you added any public properties you can to pass values into then add them inside the <parameters> tag. The name of the property should be used as the tag name. Set the value as required.

Custom Filter Template

Here is a template to use as a starter for your custom Filter. Please update any values in CAPS and make sure that it appears inside the <components> tags.
    <component id="YOUR-UNIQUE-NAME"
            lifestyle="transient"
            service="Wolfpack.Core.Interfaces.IPublisherFilter, Wolfpack.Core"
            type="YOUR-FILTER-CLASSNAME-INC-NAMESPACE, YOUR-ASSEMBLY-NAME-MINUS.DLL">
      <parameters>
        <!-- REQUIRED PARAMETERS - DO NOT REMOVE -->
        <Publisher>*</Publisher>
        <Check>*</Check>
        <!-- YOUR CUSTOM PARAMETERS HERE - THESE MUST MATCH THE CLASS PROPERTY NAME -->
      </parameters>
    </component>

Last edited May 22, 2011 at 9:15 PM by jimbobdog, version 1