Elevated Rails RSS Feed

Open Source Bridge

Wed, 20 May 2009 15:14:29 GMT

If you’re looking for a great conference to attend in June, check out Open Source Bridge. Open Source Bridge is a technology agnostic conference covering all things open source. It includes several tracks, including a track on building open source businesses and a track on cool hacks. Our own Audrey Eschright is one of the Co-Chairs. Audrey and Selena Deckelmann have put together an incredible lineup of speakers including Brian Aker (MySQL and Drizzle) Greg Kroah-Hartman (Linux Kernel) and Chris Wanstrath (Github)

If you’re anywhere near the area, I highly recommend attending.

Standing up to be counted

Thu, 30 Apr 2009 12:58:57 GMT

Nick Sieger asked that people stand and be counted and I too will join in. I’m disappointed with many in our community. While I think the presentation that sparked this discussion was in poor taste, it’s not the presentation that bothers me. I’m disappointed by how little empathy some people are showing.

Whether you agree with somebody or not, I think it’s important to try to see things from their perspective. It may not change your mind, but it will hopefully at least give you a better understanding of how your actions affect others.

Speeding up location based searches

Fri, 06 Mar 2009 09:35:51 GMT

With the popularity of Google Maps, more and more web applications are becoming location aware. Rails already has some great tools for working with geodata, such as GeoKit. We've been happily using these tools for years. While GeoKit has some basic optimizations, we recently found a case where lookups were taking close to 8 seconds. We needed a way to speed this up. Read on to learn how we did it.

First, let me explain our domain. We are working on a site that shows the 25 nearest amenities to a location. The application is focused on San Francisco and the surrounding areas. We store the amenities in a table with columns for latitude and longitude. All told, we search about 800,000 amenity records.

To find the nearest 25 amenities, our database has to do a lot of work. For each listing in the database, we need to calculate the distance from our origin. Performing that calculation would be unbearably slow, so geokit speeds up the query by including a square bounds. First, the list of locations is limited by a square 5 miles on a side (we use a big window to make sure we get amenities in more rural areas.) Once we've limited our dataset, the results are sorted by distance. Unfortunately, due to the amenity density in San Francisco, we still have to go through 10,000 records on average.

This calculation and sort is just slow. In version 5.1, MySQL includes some geospatial extensions. These extensions include datatypes for locations and spatial indexes to make spatial searches much faster. Unfortunately, ActiveRecord doesn't support these extensions. That means we'll have to do some things manually.

First, let's look at the three primitives we'll use. The first is a @Point@. Points represent a location in a 2D space. We'll use Points to represent the location of an amenity by it's latitude and longitude coordinates. In MySQL, you can create a point using the SQL: @GeomFromText('Point(38.567 -122.576)')@

The second primitive is a @Polygon@. Polygons include a list of coordinates that make up the vertices. Polygons must be closed. For example, we could create the polygon @GeomFromText('Polygon((0 0,0 1,1 1,1 0,0 0))')@. We'll use a Polygon to represent the boundary inside which we want to search.

The final primitive is a @Line@. We use a Line to calculate the distance between two points. According to the OpenGIS specification, we should be able to use the distance function for this. Unfortunately, MySQL doesn't implement Distance.

We'll also need to create a spatial index. A spatial index is an r-tree index that is optimized for fast distance calculations. Currently, only MyISAM tables support spatial indexes. They also require that the column be defined as NOT NULL. We'll have to keep that in mind as we go along.

Let's start by adding a Point column to our amenities table. Because ActiveRecord doesn't support the GIS extensions, we'll need to use the execute method inside our migration. This looks like:

    execute 'alter table amenities add lat_lng_point point not null'

Because we want to use Spatial indexes, we'll also need to convert our amenities table to MyISAM.

    execute 'alter table amenities engine myisam'

With that in place, we'll need to convert our existing data to include the @lat_lng_point@ column. From what I can tell, Points can only be created using the GeomFromText method. That means we'll need to generate the text representation of a Point during our conversion. This can be done with the following SQL"

update amenities set lat_lng_point = GeomFromText(concat('Point(',lat,' ',lng,')'))

At this point, we now have a table with the location data being stored as a Point. Since all of our records have a Point, we now meet the criteria for adding our spatial index:

    execute 'create spatial index amenities_spatial_idx on amenities(lat_lng_point)'

With that in place, we can need a method that does a few thing. First, we need to compute a bounds to limit our distance calculation. We'll do that using @GeoKit::Bounds@. Once we have that, we need to write a query that uses the @MBRWithin@ function (MBR stands for Minimum Bounding Rectangle) to find the list of points inside our Bounds. Once we have that, we can use a Line to get the distance between our origin and each point and order by that. The end result is a little ugly:

  
  def self.near(mappable)
    bound = GeoKit::Bounds.from_point_and_radius(mappable,5)
    sql = <<SQL
    select *,  GLength(LineStringFromWKB(LineString(AsBinary(lat_lng_point), 
    (AsBinary(GeomFromText('Point(#{mappable.lat} #{mappable.lng})')))))) * 69 as distance
    from amenities where MBRWithin(lat_lng_point,
     GeomFromText('Polygon((#{bound.ne.lat} #{bound.ne.lng}, #{bound.ne.lat} #{bound.sw.lng},#{bound.sw.lat} #{bound.sw.lng},#{bound.sw.lat} #{bound.ne.lng},#{bound.ne.lat} #{bound.ne.lng}))')) 
    order by distance asc limit 25;
SQL
    find_by_sql(sql)
  end

It's ugly, but it is blazingly fast! Our query went from 8s to 0.01s. That's definitely worth a little code ugliness.

While we've handled the inital data conversion and querying, we can't add data to our table. We need to provide a Point for each record, and there's no way to do that using ActiveRecord. Instead, we'll need to use a MySQL trigger.

    execute <<EOT
      create trigger set_lat_lng_point 
      before insert on amenities for each row 
      set  new.lat_lng_point = GeomFromText(concat('Point(',new.lat,' ',new.lng,')'));
EOT

That code will create a Point from the lat and lng when a record is inserted. If you need to be able to update locations, you could make the trigger fire on update as well. You'll want to install the Trigger Happy plugin so that your triggers are dumped and included in your test database.

After all that, can you believe we're still not quite done? Due to a bug in MySQL, inserting a row where @lat_lng_point@ is NULL will give an error. It turns out that MySQL checks the not null columns before triggers are run. Luckily, there is a workaround. If you don't explicitly set the column value to NULL, the trigger will be run before the value is checked. To get ActiveRecord to not explicitly set the column to NULL, we'll use a bit of a hack.

  # Remove lat_lng_point from the list of attributes
  # otherwise, AR writes it as NULL which keeps the trigger from firing
  # and setting the value correctly  
  def before_save
    @attributes.delete("lat_lng_point")
  end

That code will remove the column for AR's list of attributes.

Obviously, this is somewhat complicated. If your searches are running okay using just normal SQL, I wouldn't recommend changing. If you need high performance and are searching large amounts of data, this little bit of code can make a huge difference.

# Our entire migration
class ConvertAmenitiesToUseSpatials < ActiveRecord::Migration
  def self.up
    execute 'alter table amenities add lat_lng_point point not null'
    execute 'alter table amenities engine myisam'
    execute 'update amenities set lat_lng_point = GeomFromText(concat(\'Point(\',lat,\' \',lng,\')\'))'
    execute 'create spatial index amenities_spatial_idx on amenities(lat_lng_point)'
    execute "create trigger set_lat_lng_point before insert on amenities for each row set  new.lat_lng_point = GeomFromText(concat('Point(',new.lat,' ',new.lng,')'));"
  end

  def self.down
    execute 'alter table amenities drop lat_lng_point'
  end
end

Speeding up SOLR indexing

Wed, 14 Jan 2009 15:01:01 GMT

We're finishing up a project that uses SOLR and acts_as_solr extensively. Our dataset isn't large, but it's non-trivial as well. We're managing a search index with a little over 100,000 documents in it. Each document has indexes on 12 fields. In general, our search performance is outstanding. We get results almost instantly. Our indexing performance was another story. I'm not a big fan of premature optimization, but when a full reindex took 4 days, I decided something needed to change

There's some good advice on the web for pulling indexing out of a request flow. Unfortunately for us, this wasn't going to help. Our updates would take several days to process. This delay makes testing changes to search incredibly painful.

After much googling, I found a number of people that recommended allowing SOLR to manage its own commits. It took me a few tries to get this working. In the end, I was making it much harder than it had to be. Disabling autcommit really only takes two steps.

First, update your call to acts_as_solr to disable autcommit:

class MyIndexedModel < ActiveRecord::Base
  acts_as_solr :fields=>[:name,:body], :auto_commit=>false
end

With just that change our index performance went from 2 seconds per record to 50 records per second. A 100x speed up. Unfortunately, our changes weren't showing up in the index. SOLR doesn't add indexed records to the database until a commit is done. SOLR does provide an easy way to tell it to manage the commits itself. To enable this, edit vendor/plugins/acts_as_solr/solr/solr/conf/solrconfig.xml. There is commented out configuration for autoCommit. Remove the XML comments around this area. We use the maxTime parameter to have SOLR update the index every minute. Our configuration looks like:

...
  <updateHandler class="solr.DirectUpdateHandler2">

    <!-- A prefix of "solr." for class names is an alias that
         causes solr to search appropriate packages, including
         org.apache.solr.(search|update|request|core|analysis)
     -->

    <autoCommit>
      <maxDocs>10000</maxDocs>
      <maxTime>60000</maxTime>
    </autoCommit>
...

That's all there is to it! We get 100x faster indexing and our updates still show up within a minute. Suddenly I don't dread making changes to our indexed models!

Announcing Facebooker support for Facebook Connect

Fri, 02 Jan 2009 12:51:20 GMT

Over the last few months I've received quite a few requests for Facebook Connect support in Facebooker. Thanks to Kevin Lochner, I'm proud to announce Facebook Connect support in Facebooker. Read on to learn how to create a simple Facebook Connect application.

The setup of a Facebook Connect application is very similar to that of a Facebook Platform Application. You'll need to create an application using the Facebook Developer tool and then build a Rails application and install the Facebooker plugin. If you need help with this, check out the screencast or My Book. You'll need to set up your facebooker.yml and configure a callback URL on Facebook.

Once you've got a basic application set up and running, we'll need to generate an xd_receiver file. The xd_receiver file allows Facebook to perform cross domain javascript requests. You can generate this file by running:

  script/generate xd_receiver

A file named xd_receiver.html will be generated and placed in your public directory. Make sure this file is added to your source code control system. It must exist for Facebook Connect to work.

With that setup done, it's time to try out Facebook Connect. Before we can do anything else, we'll need to ask our user to login. Let's create a controller and an action for testing. I called my controller "connect" and just used the index action because I'm lazy. Inside the view for action, we'll need to include a javascript file and do a little setup. Add this to your view:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">
<head>
  <%= javascript_include_tag :defaults%>
</head>
<body>
<h1>My Great Application</h1>
<%= fb_connect_javascript_tag %>
<%= init_fb_connect "XFBML"%>
<%= fb_login_button%>

</body>
</html>

Facebook connect requires an XHTML doctype declaration along with a namespace on your HTML element. It also works most reliably if your HTML is valid. If you're getting strange results, it's worth validating your HTML. The three calls to helpers are the actual meat of the view. The first call includes the Facebook Connect javascript. The second line runs a little setup and the final line renders an <fb:login-button> tag.

If all goes well, you should see something that looks like:

If you don't see that, you'll need to verify that things are configured just right. There's a lot of magic going on and it tends to be brittle. Make sure that your callback URL is correctly set and that you are accessing your site using the callback URL. Make sure that your public/xd_receiver.html file exists. Finally, make sure that you have correctly set up your facebooker.yml file.

Take a look at the source of your page. Doesn't that <fb:login-button> tag look strange? To render FBML inside your page, Facebook is using into the HTML equivalents. The login button is just one of many tags we can use. For example, we can include a user's profile photo by calling fb_profile_pic. Add a call to show your own profile. Once you've done that, you should see something like: Notice that Facebook isn't showing your picture. That's because of privacy restrictions. Before we can see information about a Facebook user, we'll need to login. Click the "connect" button and you should see a popup prompting you to log in. After logging in, your profile picture will now be shown.

Getting access to FBML outside of the Facebook canvas is cool, but it's just a start to what we can do. When we login using Facebook Connect, Facebook sets several cookies that our application can use to access a Facebook session. Facebooker knows how to use these cookies to set up a facebook session. Add the following code to your controller:

  before_filter :set_facebook_session
  helper_method :facebook_session

That code sets up the users Facebook session and makes it available to the view. With it, you have access to the normal REST API as you can see in the following code.

<% if facebook_session %>
  <h2>You are logged in as <%= facebook_session.user.name %></h2>
<% else %>
  <h2>You are not logged in!</h2>
<% end %>

This means you can ask for data about a user like their name and their friends. You can also post stories to their feed! You have most of the power of a Facebook Platform application inside your existing code!

This support is still very new, so make sure you join the Facebooker mailing list on Rubyforge if you decide to use it. Let us know what you build with it!

Thanks again to Kevin Lochner who provided the patch to support authentication using cookies. Thanks also to Nate Kontny of Inkling Markets who provided a great overview of how Facebook Connect works! Happy New Year everyone!

Daemonizing Rails

Tue, 02 Dec 2008 15:02:54 GMT

No, this isn't a post about us converting from Linux to BSD. Instead, I'm talk about starting long running processes that use the Rails environment. If you've tried to do this, you've probably seen some obscure errors like:

closed stream 
activesupport-2.1.0/lib/active_support/buffered_logger.rb:105:in `write'
activesupport-2.1.0/lib/active_support/buffered_logger.rb:105:in `flush'
activesupport-2.1.0/lib/active_support/buffered_logger.rb:118:in `auto_flush'
activesupport-2.1.0/lib/active_support/buffered_logger.rb:70:in `add'
activesupport-2.1.0/lib/active_support/buffered_logger.rb:76: ...

Inside, I'll show you how to avoid this

Daemons in UNIX are a wonderful, magical thing. Even though it seems like starting up a background job should be simple, there are a lot of steps involved. You can see them in detail in Tammer Saleh's Angels and Daemons talk. The really interesting issue for us is that processes close all open IO streams when they daemonize. That may not cause a problem for a normal Ruby Application, but it violates some assumptions that Rails makes.

When Rails boots, it opens a few different file descriptors. First, it opens a log file. This is your production.log or similar. It also makes a connection to the database. Rails gets unhappy when these files are closed out from under it. You could write a lot of code to handle these conditions or you can take the simple way out: Delay booting Rails until after you daemonize. Here's a simple script that does that:

#!/usr/bin/env ruby
require 'rubygems'
require 'daemons'
ROOT = File.expand_path(File.dirname(__FILE__)+'/../')
Daemons.run_proc('watcher', :dir_mode => :normal, :dir=>"#{ROOT}/log/",:log_output =>true, :backtrace=>true) do
  require "#{ROOT}/config/environment"
  # Do work here
end

This code is simple, but there are a couple of subtleties. The first is that we need to use File.expand_path to turn the Rails Root path into an absolute path. When an application daemonizes, it changes its working directory to "/". If we use a relative path for our RAILS_ROOT it will no longer point to our Rails installation.

Once we have the absolute RAILS_ROOT path, we can daemonize and then boot Rails. Rails will now start as usual and all files will be opened. That's all there is to it. Now you can easily start long running processes using Rails. You can even use a cap task to easily restart them on deploy:

task :restart_watcher do
  run "#{current_path}/script/watcher restart"
end

It feels good to see your name in print

Wed, 22 Oct 2008 11:11:51 GMT

It was almost a full year ago that I started writing a book on Facebook development. This past Friday I got a very exciting box. Unboxing pictures inside.

A nice note on top of the box.

Carefully wrapped

There it is.

I really underestimated the amount of work it would take to write a book. I had read Dave Thomas’ So You Want to Write a Book so I should have realized what an undertaking it was. I had just completed my first marathon at that point and figured it couldn’t be harder than running 26.2 miles. Boy was I ever wrong. I’m proud of the book. I know it is something I would have loved to have when starting to develop Facebook applications.

Now I’m going to get back to training for the Philly Marathon on 11/23. Training seems much easier now.

Preloading summary data using ActiveRecord

Wed, 08 Oct 2008 10:55:21 GMT

It seems like every application we build has at least one screen that needs to access a lot of data. For example, if we were building a web application for a school we would likely have a page for teachers that shows all of their students including their current grage, number of assignments turned in on time and attendance. Inside, we'll look at how we can make this type of page run quickly without adding much complexity.

Let's set up a couple of example models to demonstrate this case. We'll have a student model. Our student will have a list of absences, a list of assignments and a list of grades. Our model could look something like:

class Student < ActiveRecord::Base
  has_many :assignments
  has_many :grades, :through => :assignments
  has_many :absences
end

In our output, we'll want to show a tabular view of information for each student. A first cut would probably look something like:

  <% for student in @teacher.students %>
    <tr>
      <td><%= student.name %> </td>
      <td><%= student.absences.count %> </td>
      <td><%= student.assignments.select {|a| a.on_time?}.size / student.assignments.size.to_f rescue nil %> </td>
      <td><%= student.grades.sum(:score)/student.grades.count %> </td>
   </tr>
  <% end %>

That code works, but there are a couple of obvious problems with it. First, we have a lot of logic in our views. Second, we'll run 4 queries for each user: 1 to count absences, 1 to get the number of on_time assignements, 1 to get the total score and one to count the number of grades. This is okay for viewing 10 students, but performance will become a serious problem when looking at a couple of hundred students.

So how do we clean this up? Let's start by cleaning up the logic in the views. Hopefully that will make a solution more apparent. The first step is to create methods on student for each of those items. Instead of calling student.absences.count in the view, we can add a student.times_absent method. We can do the same for the percent of on time assignments and for the average score. Our code then becomes:

  <% for student in @teacher.students %>
    <tr>
      <td><%= student.name %> </td>
      <td><%= student.times_absent %> </td>
      <td><%= student.percent_assignments_on_time %> </td>
      <td><%= student.average_score %> </td>
   </tr>
  <% end %>

Our implementation of those methods will look familiar:

class Student < ActiveRecord::Base
  has_many :assignments
  has_many :grades, :through => :assignments
  has_many :absences
  
  def times_absent
    absences.count
  end
  
  def percent_assignments_on_time
    student.assignments.select {|a| a.on_time?}.size / student.assignments.size.to_f rescue nil
  end

  def average_score
    student.grades.sum(:score)/student.grades.count
  end 

end

That cleaned up our code, but it didn't do anything for our performance. We could try to use :include to speed up our query. If we had 200 students each with 200 assignments, this would involve us running a find that returns 200*200 rows. Another solution to our performance problem is to use a raw sql query. We can write a sql query that will give us the percent_assignments_on_time and the average score for our whole list of users at once. I normally avoid doing this because then I can't lose the abstraction that active record provides. What if we could keep the same interface but use a sql query to preload the data? That would be the best of both worlds.

We can do this using memoization. To implement this, we'll start by adding memoization to our methods:

  def average_score
    @average_score ||= student.grades.sum(:score)/student.grades.count
  end

Next, we'll create a method that will retrieve and set the average score for each user that we care about. It will look something like:

  attr_accessor :average_score, :percent_assignments_on_time
  def self.load_assignment_analytics!(students)
    sql =<<-SQL
      select u.id, 
             avg(score) as cached_average_score,
             sum(on_time)/count(*) as cached_on_time_percent
      from students u
       join assignments a on u.id = a.user_id
       join grades g on g.assignment_id = a.id
      where u.id in (?)
      group by u.id
    SQL
    assignment_info = Student.find_by_sql([sql,false,users.map(&:id)])
    user_map = assignment_info.index_by(&:id)
    students.each do |student|
      rec = user_map[student.id] 
      if rec.nil?
        student.percent_assignments_on_time = "None"
        student.average_score = "None"
      else
        student.percent_assignments_on_time = rec. cached_on_time_percent.to_f
        student.average_score = rec. cached_average_score.to_f
      end
    end
    
  end

That methods runs our query for all users that we pass in. For each user, it finds the result from our query. If no result exists (because they don't have any assignments or grades) it will set the values to "None". (If we set them to nil or false our query would be re-run in the interface because of the ||= line. If there are results for a user, we set the value on the object.

Now, when our view iterates over the list of users, it will use the previously stored data. The interface remains the same but our performance improves just by adding a single call to Student.load_assignment_analytics!(teacher.students) in our controller. If we forget to call this method, the view will still work, it will just run more queries. This is definitely less DRY than our original code, as we implement the logic for our counts in two ways. We could redefine our average score method to always call load_assignment_info!, but that might be overkill. There are also a couple of gotchas. Because we use Student.find_by_sql to fetch our data, we need to make sure that we name our calculated constants something that isn't a method name on student. If you don't, the method will be called.

All in all, I think this is a relatively elegant and simple solution to a complex problem.

Developing Facebook Platform Applications with Rails is done!

Thu, 25 Sep 2008 10:04:45 GMT

I've been busy recently, as you may have guessed from the lack of posts. It's time to share the items I've been working on!

First, I’m thrilled to announce that Developing Facebook Platform Applications with Rails is being printed. It should be shipping withing the next couple of weeks. If you haven’t ordered your copy, pick one up now. All told, it took about 10 months to get the book out. That’s definitely longer than I hoped, but there is a good reason. Facebook released a massive overhaul of their platform about 3 months ago. The shipping version of the book has been completely updated to reflect this new API. It took a lot of work, but I’m happy with how it turned out. You can check out the application we build on Facebook. You can also see the code on github. I’d love for some intrepid readers to fork the code and send me patches to make the application prettier!

In other Facebook news, I released a plugin called facebooker_authentication that encapsulates a lot of the code that we use on Facebook applications. It covers user creation, user authentication and some helpers for handling users. I’ve used something similar on every application. In fact, I use this plugin on two forthcoming screencasts for the Pragmatic Programmers. Expect another announcement here when that happens.

Finally, I’m still getting settled into Philadelphia. It’s a great city with some fun people. I’ve spent a couple of days at Indy Hall and really dig it. I’ve also been volunteering with a group called Back On My Feet that supports the homeless population in Chicago. I’m running the Philly marathon on their behalf. Check out my story and make a donation!

Painless monitoring with Scout

Wed, 06 Aug 2008 10:43:34 GMT

I write about monitoring from time to time. We host about 15 applications for our clients, so monitoring our servers is a high priority for us. We've experimented with a large number of tools including monit and god. Both work great as process monitors, but they aren't built for some of our most important tasks. Enter Scout. In less then a week I've been able to port all of our ad-hoc monitors to Scout. See inside for more information.

What makes Scout great is its configuration and plugin architecture. When a host runs it's monitors, it talks to Scout to download an executiong plan. This plan includes a list of plugins to execute. If a plugin has been added, the client will automatically download the required code. This makes it trivial to change monitors via the web and have your clients update automatically.

A Scout plugin is just a simple Ruby class that either returns data, sends and alert or raises an error. It provides a very simple architecture for adding new plugins. This means that unlike with monit, you can create monitors that are tailored to your environment.

Let's look at an example. Weare heavy users of Starling. We want to be able to monitor certain queues to make sure that our processors are running. Doing this under monit was a hack. I wrote a ruby program to read the queues and touch a watchdog file when the queue depth is below a threshold. I configured monit to raise an error when a file's timestamp was older than a set interval. This worked in practice, but it was complicated to set up and required modifying multiple pieces any time a change was required.

I was able to replace my cobbled together monitor in just a few minutes with Scout. Here is the full code to my new plugin:

class MissingLibrary < StandardError; end
class StarlingMonitor < Scout::Plugin

  
  attr_accessor :connection
  
  
  def setup_starling
    begin
      require 'starling'
    rescue LoadError
      begin
        require "rubygems"
        require 'starling'
      rescue LoadError
        raise MissingLibrary
      end
    end
    self.connection=Starling.new("#{option(:host)}:#{option(:port)}")
  end
  
    
  
  def build_report
    begin
      setup_starling
      connection.sizeof(:all).each do |queue_name,item_count|
        check_queue(queue_name,item_count) if should_check_queue?(queue_name)
      end
      report(@report)
    rescue  MissingLibrary=>e
      error("Could not load all required libraries",
            "I failed to load the starling library. Please make sure it is installed.")
    rescue Exception=>e
      error("Got unexpected error: #{e} #{e.class}")
    end
  end

  def should_check_queue?(name)
    option(:queue_re).nil? or /#{option(:queue_re)}/ =~ name
  end
  
  def check_queue(name,depth)
    q_depth = (depth||0).to_i
    @report ||= {}
    @report[name] = q_depth
    if q_depth > option(:max_depth).to_i
      alert("Max Queue Depth for #{name} exceeded","#{q_depth} items is more than the max allowed #{option(:max_depth)}")
    end
  end

end

There's a bit of code, but it is pretty simple. Scout starts our plugin by calling the build_report method. In build_report, I do a little setup to make sure can load all of the required libraries. After requiring in Starling, I make a connection. The plugin uses the option method to pull configuration information from the environment. Scout provides a simple configuration interface that allows plugins to be configured via the web.

After loading up the environment, I walk the list of matching queues and send any necessary alerts. After looking at all queues, I return a report that maps the name of each queue to its depth. Along with providing an alert infrastructure, Scout also stores your reported data and can plot it on a graph. For example, here is a graph of the depth of our starling queues on one server:

This simple interface to reporting and alerting is incredibly powerful. What makes it even more powerful is the ease at which you can install plugins. If you want to install my starling plugin, you can simply enter the URL to the Ruby file from github (http://github.com/mmangino/er-scout-plugins/tree/master%2Fstarling_monitor%2Fstarling_monitor.rb?raw=true)

As I said, I've moved all of my ad-hoc monitoring to Scout. I had to create a few plugins to make that work. They're available on Github at http://github.com/mmangino/er-scout-plugins/tree/master. Feel free to fork them and submit enhancements!

So far, using Scout has been a real joy. That's something I never thought I would say about a monitoring tool.