Getting Started

This provides information on installation and configuration of MonitorWang.

Custom plugin development

If you just want to develop either a new custom HealthCheck or Publisher then the quickest route is via the NuGet packages. MonitorWang is now on NuGet! Rob Gibbens has created the NuGet packages to support & streamline custom HealthCheck and Publisher development. These contain just the binaries required to develop either of these plugins for MonitorWang. You can get the packages from the NuGet gallery using the links below or via the online package browser in Visual Studio - just search for "MonitorWang"...
Thanks Rob, great job!

Installing and running MonitorWang

To start with, download the latest binaries zip (or source and build it yourself). MonitorWang is based on the TopShelf windows service framework. This means you can run it as either a console application (recommended whilst you evaluate) or install it as an unattended windows service (recommended for real use).

To run it as a console application, open a command prompt and type,
monitorwang.agent.exe
To install and execute it as a windows service running under the Local System account, open a command prompt and type,
monitorwang.agent.exe /install
To install and execute it as a windows service running under the custom account, open a command prompt and type,
monitorwang.agent.exe /install /username:[DOMAIN\Account] /password:[Password]
To uninstall it as a windows service, open a command prompt and type,
monitorwang.agent.exe /uninstall
There are several "profiles" that alter the behaviour of MonitorWang. Supported profile names are,
  • FastStartAgentProfile - this will asynchronously startup the agent so that control is quickly returned to the Windows Service Control Manager - this stops timeouts occurring when you have a large number of plugins configured and enabled. Access these additional profiles with,
monitorwang.agent.exe /profile:[profile name]

Configuring MonitorWang

MonitorWang uses Castle/Windsor as it's IoC/Container. I've hopefully abstracted the concrete Windsor container away from the code so it should be possible to replace the IoC/Container with another framework if desired. The main use of the Container is to register "configuration" components which are used to infer and load an associated component that performs as either a "Publisher", "HealthCheck", "Activity" or "Scheduler".

A full list of container configuration files is below but there are three main ones in the config folder to play around with initially, the check, publisher and binding config files.

The check.castle.config file contains the setting for each individual health check that MonitorWang executes. The only rule is that each one has to have a unique component id attribute value and a unique "FriendlyId" value, so it makes sense for these to be the same. Each "component" represents a health check instance. If the "Enabled" property is true then MonitorWang will query the binding.castle.config file to try to link it to a schedule (when it should execute) - if it finds a match it creates an instance of the health check and starts running it on the schedule indicated in the binding.

Configuration by Example

One of the example HealthChecks is "IsNotepadRunning" - so lets use this as a template for your first configuration modification, we'll create a new HealthCheck to check for the calc.exe process.
1. In the check.castle.config file, copy the IsNotepadRunning" component and rename the id attribute and "FriendlyId" property to "IsCalcRunning".
2. Change the "ProcessName" property to "calc.exe".
    <component id="IsCalcRunning"
				   lifestyle="singleton"
				   type="MonitorWang.Core.Checks.WmiProcessRunningCheckConfig, MonitorWang.Core">
      <parameters>
        <FriendlyId>IsCalcRunning</FriendlyId>
        <Enabled>true</Enabled>
        <RemoteMachineId>localhost</RemoteMachineId>
        <ProcessName>calc.exe</ProcessName>
      </parameters>
    </component>
3. Update the binding.castle.config file, find the "IsNotepadRunningBindingConfig" component and copy it
4. Rename the component id to "IsCalcRunningBindingConfig".
5. Update the "HealthCheckConfigurationName" property to "IsCalcRunning" (this "binds" our new HealthCheck to the schedule named "EveryMinute")
    <component id="IsCalcRunningBindingConfig"
				   lifestyle="singleton"
				   type="MonitorWang.Core.Interfaces.Entities.BindingConfiguration, MonitorWang.Core.Interfaces">
      <parameters>
        <HealthCheckConfigurationName>IsCalcRunning</HealthCheckConfigurationName>
        <ScheduleConfigurationName>EveryMinute</ScheduleConfigurationName>
      </parameters>
    </component>
6. Restart MonitorWang, you should see your new HealthCheck "IsCalcRunning" appear. Try opening calc.exe and leave it running for a few minutes, then close it....MonitorWang should start to report failures when it is not running (remember it's not instant as it only checks once a minute).
7. That's it - you have created your first HealthCheck by reconfiguring MonitorWang. Remember you can create as many checks as you like; you can even create new "schedules" for them by creating new entries in the schedule.castle.config file. Just remember to add an entry in the binding.castle.config file to link the two together - its job as its name implies is to bind a HealthCheck to a Schedule.

UPDATE - 7th Dec 2010, v1.0.4* - I've exposed some Castle namespace components out via the "Container" helper which means MonitorWang is now locked to Castle - this was required to get the Publisher Filter functionality to work as it uses Castle Interception - the good news is that I was being a bit lazy and didn't want to create MonitorWang wrappers over the components and exposed the Castle ones directly so it would be possible to put Castle "back in the box" - you would also need to implement your own Publisher Interception mechanism in what ever IoC container you replace Castle with.

The Config application subfolder mainly contains the configuration files for each of these component roles,
  • activity.castle.config - registers the configuration component for an "Activity"
    • This is a standard Castle component configuration file
    • WCF Service "Uri" - where the service listens
    • NSB queue to receive MonitorWang data
  • binding.castle.config - this is used to associate a HealthCheck to its Scheduler
    • This is a standard Castle component configuration file
    • The component "id" must be unique but is otherwise not important
    • The HealthCheckConfigurationName & ScheduleConfigurationName property values must match a component "id" in the check.castle.config and scheduler.castle.config file respectively.
  • check.castle.config - this is used to provide configuration to each HealthCheck.
    • This is a standard Castle component configuration file
    • The FriendlyId must be supplied and be unique across all HealthChecks
  • filter.castle.config - this is used to provide configuration to each Publisher Filter
    • This is a standard Castle component configuration file
  • finaliser.castle.config - this is used to provide configuration to each Growl Notification Finaliser
    • This is a standard Castle component configuration file
  • log4net.config - standard log4net config, see http://logging.apache.org/log4net/release/config-examples.html for more details.
    • Errors are output to the monitorwang.log file in the application folder - check this if you have trouble starting the service.
  • publisher.castle.config - this configures each publisher
    • This is a standard Castle component configuration file
    • WCF publisher, the "Uri" property must match the WCF Service Activity Uri
  • role.castle.config - this provides configuration for the MonitorWang instance
    • This is a standard Castle component configuration file
    • SiteId is the name of the instance and should be unique per MonitorWang installation. It is used to identify the origin of monitoring data
  • scheduler.castle.config - provides the configuration to the schedulers. You can create as many of these as you like with whatever intervals you require. Just use an entry in the binding.castle.config to associate a HealthCheck with the Schedule via the component "id".
    • This is a standard Castle component configuration file
Activity, HealthCheck and Publisher config components all support an "Enabled" property - set this to "true" or "false" as desired; this provides a very quick way of changing the behaviour of the monitor without having to comment out/removed whole sections of configuration.

Important... by default, only the Growl publisher is enabled. I chose this one as, although it requires you to install Growl it's a visible and simple method to demonstrate that MonitorWang is working. See this guide on setting up Growl (and the other publishers).

Remember to configure the activities, publishers and healthchecks before you start MonitorWang. Restart MonitorWang to pick up any changes you make to these files whilst it is running.

Remember the account you run MonitorWang under as a service must have permissions to perform the checks you have configured it for. For instance, if you are using the MSMQ checks the service account must have the correct permissions on the MSMQ in question.

Last edited May 15, 2011 at 5:54 AM by jimbobdog, version 19

Comments

No comments yet.