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 lib/scount_agent.

dispatcher.rb, assignment.rb, and assignment/:: This is the code the agent uses to interpret commands users give on the command-line. You'll find configuration file loading (plan.rb is a configuration), switch parsing, command selection, and invocation in here. api.rb:: 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. lifeline.rb and agent.rb:: 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. agent/master_agent.rb and mission.rb:: 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. agent/communication_agent.rb, order.rb, and order/:: 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. database.rb and database/*:: 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. core_extensions.rb:: 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.