highgroove / scout_agent

= The Scout Agent

This is the agent software installed on servers to work with {the Scout monitoring application}[http://scoutapp.com/].  
See the sections below for details on how to install and use the agent, how to build your own plugins for it to track 
the data you care about, and how to add features to the agent itself.

== How do I use the Scout agent?

Installing the agent is just a simple gem install:

  $ sudo gem install scout_agent

Note that the gem requires Ruby 1.8.6 or higher and Rubygems 1.3.1 or higher.  It also doesn't run on Windows due to 
Ruby not supporting fork() there.

Once the gem is installed, you need to identify yourself with the agent key (which looks like 
a7349498-bec3-4ddf-963c-149a666433a4) that you get from the Web application.  Just issue this command and have your key 
ready when it asks for it:

  $ sudo scout_agent id

At this point, you should be all set to run the agent.  You start it up with this command:

  $ sudo scout_agent start

The agent is a daemon, so it should return your prompt after it moves into the land of background processes.  It will be 
running though.  You can issue the following command if you want to check up on it:

  $ scout_agent status

With the agent running, you should be able to log into your account on the {Web application}[http://scoutapp.com/] to 
setup your list of plugins and see the agent delivering data.

== How do I build my own plugins?

Scout makes it very easy to build your own plugins for anything you need to monitor.  In a matter of minutes you could 
be tracking the user sign-ups in your application or anything else that's important to you.  Once you pipe some data 
into Scout you can take advantages of all the graphing and trend analysis we use for more traditional monitoring, like 
Rails applications.

We have {a tutorial}[http://scoutapp.com/plugin_urls/static/creating_a_plugin] on the Web site that walks you through 
building a Scout plugin.

== How do I hack on the agent?

We try to keep the agent code fairly clean and documented, so it's hopefully not too tough to poke around in.  However, 
it is a big code base.  Let me give you the dime tour of where to look for things.  All paths below are relative to 
<tt>lib/scount_agent</tt>.

<tt>dispatcher.rb</tt>, <tt>assignment.rb</tt>, and <tt>assignment/*</tt>:: This is the code the agent uses to interpret 
commands users give on the command-line.  You'll find configuration file loading (<tt>plan.rb</tt> is a configuration), 
switch parsing, command selection, and invocation in here.
<tt>api.rb</tt>:: The ScoutAgent::API is the external interface for the queue and snapshot commands.  This can be used 
to push data into Scout, without even building a Plugin, or just to request an updated snapshot of the environment.
<tt>lifeline.rb</tt> and <tt>agent.rb</tt>:: The ScoutAgent::Lifeline object monitors a ScoutAgent::Agent class, which 
is a major function of Scout, namely the plugin runner and the XMPP communication module.  This is a pretty typical 
multi-process heartbeat setup where the Agent is fork()ed into a separate process and then monitored for regular 
check-ins written to a shared pipe.
<tt>agent/master_agent.rb</tt> and <tt>mission.rb</tt>:: Together these two pieces make up the heart of the agent.  The 
ScoutAgent::Agent::MasterAgent is the main event loop and ScoutAgent::Mission (aliased Plugin) are the pieces of code 
that get run in that loop.
<tt>agent/communication_agent.rb</tt>, <tt>order.rb</tt>, and <tt>order/*</tt>:: This code is used to listen for 
supported commands over an XMPP connection.  The ScoutAgent::Agent::CommunicationAgent manages all the XMPP talking and 
ScoutAgent::Order and subclasses are the commands.
<tt>database.rb</tt> and <tt>database/*</tt>:: This is a thin wrapper over 
Amalgalite[http://copiousfreetime.rubyforge.org/amalgalite/] (and SQLite databases by extension).  These are the memory 
of the agent and, with locking, the primary IPC used used by the agent.
<tt>core_extensions.rb</tt>:: This file holds a handful of extensions that make sense in the context of the agent.  This 
is not an ActiveSupport size library, but just some simple niceties.  These extensions can be used in your own Plugins.


We welcome additions to the agent and will incorporate patches if we feel they add to the platform as a whole.  
Obviously, the easier we can understand what you did the easier it is to judge that, so tests and documentation are 
plusses to us.