How To Create a Scout Plugin

We've been building and sharing Scout plugins for common server operations in the plugin directory. There are plugins ranging from monitoring the memory usage of processes to tracking your popularity on the Internet. What if you need a variation of a plugin though? How about creating a brand new plugin?

This is what makes Scout really powerful - you can customize it with your own plugins. If you think others might benefit from your plugin, you can also submit it to the directory.

Writing a plugin for Scout is very easy. You only need to know a few simple rules and you can generally be gathering new information with just 10 to 15 minutes worth of work. Let me show you what I mean.

Preparing to build a Scout plugin is extremely simple. Step one, make sure you have Scout installed:

Create a minimal plugin file that Scout can work with. Very little is needed here. Basically the steps are:

1. Create a class_name.rb file to hold your plugin
2. Build a standard Ruby class that inherits from `Scout::Plugin`
3. Add a `run()` method that returns a `Hash` of information to record

Yes, it's really that trivial. Following those rules, I placed the following code in itunes_track.rb:

class ItunesTrack < Scout::Plugin
  def run
    { }
  end
end

I doesn't do much yet, but that's a minimal Scout plugin. I'm going to collect the statistics on the currently playing track in iTunes, of course. What could be more critical?

Most often you will want to send Scout some report data. The `Hash` returned by your method is the data that will be sent to Scout. You may optionally want to send an important alert with or without report data. And when a plugin fails to run correctly, you can send an error.

A report is a `Hash`. You make up the field names and values so they are meaningful to you. Alerts and Errors are `Hash`es as well with one required key, `:subject`, and one optional key, `:body`. Alerts are used to notify when certain conditions have been met or a threshold has been passed. Errors are only used if there is a problem running the plugin.

Here's a plugin that shows how we might use report data, alerts, and errors:

class TypicalReports < Scout::Plugin
  def run
    begin
      if Date.today == Date.parse("Dec 25 2008")
        { :report => { :holiday => "Christmas" } }
      elsif Date.today == Date.parse("Oct 31 2008")
        { :report => { :holiday => "Halloween" },
          :alert =>  {:subject => "Trick or Treat!"} }
      else
        { }
      end
    rescue
      { :error => {
          :subject => "Could not run the plugin",
          :body    => "Please check the code and try again."
        } }
    end
  end
end

This Plugin is quite trivial, simply sending back data only on certain holidays, and alerts only on those special holidays. Let's find out how to test this plugin.

Often you will want to try out a plugin on the server it will run on to be sure it works as you expect. Publishing the plugin, uploading everything to Scout and repeatedly running the client is too much hassle for those cases. That's why Scout can also simply run a plugin locally. Simply run the Scout Client with the -p or --plugin option, passing the path to the plugin file.

Here's how we can try out the code above, pretending that today is Halloween:

Enough background. Let's get back to our critical iTunes plugin.

Most plugins just gather data from the server using external tools and send that data on up to Scout. That strategy will work for us here too. We can ask AppleScript what's playing using Ruby's tools for talking to external processes and build our report off of that output.

Here's the code for that:

class ItunesTrack < Scout::Plugin
  APPLESCRIPT = <<-END_AS
  tell application "iTunes"
    try
        if not (exists current track) then return
        get name of current track
    end try
  end tell
  END_AS

  def run
    current_track = IO.popen("osascript", "r+") do |as|
      as << APPLESCRIPT
      as.close_write
      as.read
    end
    if current_track.empty?
      {:alert => {:subject => "Your mac is currently tuneless!"} }
    else
      {:report => {:track_name => current_track} }
    end
  rescue Exception
    { :error => { :subject => "Couldn't use `osascript` as expected.",
                  :body    => "An exception was thrown:  #{$!.message}" } }
  end
end

As you can see, the only remotely tricky code in here is the call to `IO.popen()`. I use that call to open a pipe to the osascript tool. Once open, I push some AppleScript code into the pipe and close my ability to write to it so it will run the code. Then I just read back the response and act on it.

Scout provides a way for you to store data between runs. We call this a plugin's memory. The most common use-case for this is to set some kind of flag so that your plugin doesn't continue to generate alerts. To get something from the memory, simply access it through the @memory hash. To put something in the memory, simply assign it a key and value. To remove something from memory, simply set its value to nil.