Support

How Scout Works

• How do I use the Scout Agent?
• What are the Scout Agent system requirements?
• How does the Scout Agent execute plugins?
• Scout retrieves plugins via HTTP. What happens if the resource is no longer available?
• What happens if a new version of a plugin is released?
• How does Scout approach security?
• I already have a Scout Account. Where do I login?
• Is Scout open source?
• How frequently does the agent run plugins on my server?
• How long does it take for data to appear on my Scout account?
• Which user account runs the Scout Agent?

Running on System Reboot

• How do I make sure Scout starts when my server is rebooted?
• How do I start Scout using init.d?
• How do I start Scout using launchd?
• How do I start Scout using cron?

Troubleshooting

• Where is the Scout log file located?
• I'm stuck. How do I get help?
• more coming soon ...

Inserting Report Data Into Scout

• Can I associate report data with an arbitrary time?
• Scout isn't graphing fields it should be (or vice versa). Does report data need to fit a certain format?
• Is there a maximum size for a report field name?

Everything Else

• I'm having problems authenticating to retrieve RSS Feeds.

How do I use the Scout Agent?

Installing the agent is just a simple Ruby gem install:

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 as Ruby not supporting fork() on this operating system.

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:

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

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:

With the agent running, you should be able to log into your account on the web application to setup your list of plugins and see the agent delivering data.

What are the Scout Agent system requirements?

The Scout Agent has been tested on the following operating systems: Linux, Apple OSX, and Solaris. Ruby 1.8.6 or higher and Rubygems 1.3.1 or higher must be installed.

How does the Scout Agent execute plugins?

The Scout Agent retrieves the plugin plan at regular intervals from the Scoutapp.com server. The plugin plan includes the plugin code plus any plugin-specific options you've set. The agent then executes the code, with the provided options, and reports back the results to Scout.

Plugins are not manually installed on the agent. You configure all plugins in the Scout web interface. Once the Scout Agent is installed, you're done!

Scout retrieves plugins via HTTP. What happens if the resource is no longer available?

Scout caches the plugin code upon installation, so you'll be able to execute the plugin code whether or not the resource still exists.

What happens if a new version of a plugin is released?

Scout will never update the code running on your server without your explicit instructions to do so. If a new version of a plugin is released, the plugin won't be updated with the new code. If you wish to update a plugin to a new version, just click the "Update Code" button on the Plugin Settings page.

How does Scout approach security?

To answer that, let’s look at the architecture of Scout first:

• You install the Scout Agent (which is a Ruby gem) on your server.
• The agent connects over https (always) through a 256-bit secure, encrypted connection (the same encryption your bank uses).
• Scout never logs in to any of your servers.
• All communication is initiated by the agent.
• The agent downloads a pre-loaded plugin plan, consisting only of plugins of your choosing, so it cannot run plugins you didn’t explicitly authorize.
• The server also uses that same secure encryption for all communication. Individual accounts are protected.
• Agent keys (uniquely generated) can be revoked at any time, disabling the agent.

The security measures needed for Scout are the same as for any other software. In fact, in some ways, it’s easier to be more secure – the plugins are relatively few lines of code and easy to review. For a more closed environment, you can create a copy of the plugin code and host it on one of your own servers (a plugin is plain text).

I already have a Scout Account. Where do I login?

Your unique Scout Account URL should have been e-mailed to you when you signed up. We do not expose a public login interface to your Scout Account for security reasons.

Contact us at support@highgroove.com if you need help.

Is Scout open source?

The Scout agent is completely open source. The gem is a normal Ruby gem, open for development, available on GitHub and distributed under the MIT and/or Ruby License (whichever you prefer). We share a collection of open-source Scout Plugins surrounded and fostered by a community that encourages branching, fixes, and general open-ness. Scout plugins can be accessed via GitHub.

The Scout Server -- which handles the data collection, analysis, trending, and notifications -- is not open-source. We maintain the server, and keep all your data safe and sound.

How frequently does the agent run plugins on my server?

The agent runs plugins every 3 minutes.

How long does it take for data to appear on my Scout account?

Typically it takes less than 5 minutes for data to appear on your account.

Which user account runs the Scout Agent?

The agent needs to be started with root privileges to setup its work environment. When setup is complete, the agent will try to switch to a standard low privilege account. By default it will look for a "daemon" account and if that can't be found it will try "nobody." These are typical accounts for such purposes on Unix servers, but you are free to select any account you prefer (see /etc/scout_agent.rb for instructions).

This startup process is very typical for Unix daemons.

How do I make sure Scout starts when my server is rebooted?

Under normal running conditions, you need to do nothing to ensure the Scout Agent continues to run, as it monitors itself. You have the standard options to ensure the agent is properly restated after a server reboot: init.d or launchd (depending upon your system), or you can use a cron restart schedule.

If you call scout_agent start while the agent is already running, it will be a null-op — the agent will not allow more than one instance of itself to run at a time. So if you want to be especially conservative, a one-minute cron job adds safety at a minor CPU cost. However, it is almost certainly overkill for a self-monitoring process like the agent.

How do I start Scout using a cron file?

There are several flavors of cron. To set a cron job for a specific user:

Solaris uses a different format for specifying the interval. To run Scout every 10 minutes, use the following format:

For example:

For more help on cron and the crontab file, see this Unix Crontab Reference.

How do I start Scout using init.d?

Coming soon.

How do I start Scout using launchd?

Coming soon.

Where is the Scout log file located?

The default location of the Scout Agent log file is:

Reviewing the log is a good starting point when troubleshooting plugins.

I'm stuck. How do I get help?

Contact us at support@highgroove.com. We usually respond in a couple of hours. Please provide your operating system, account name, your agent log file and any error messages you received.

Can I associate report data with an arbitrary time?

No - you can't insert historical data into Scout.

Scout isn't graphing fields it should be (or vice versa). Does report data need to fit a certain format?

If a field has a nil value, it won't be graphed. Instead, return zero.

Is there a maximum size for a report field name?

Yes - the maximum size of a report field name is 30 characters. If the field name exceeds 30 characters, then it will be truncated to 30 characters. For example:

# use a report field that is longer than 30 characters
field_name = 'This is a very long report field name'
field_name.size => 37
# This becomes the following in Scout:
field_name[0..29] => "This is a very long report fie"

I'm having problems authenticating to retrieve RSS Feeds.

Scout's RSS Feeds are protected with Basic Authentication and use the same credentials as your Scout login (email & password). However, you can't type the '@' symbol of your email address in a URL. Instead, replace '@' with '%'. For example, if my email address was "dog@highgroove.com": http://dog%highgroove.com:pass@scoutapp.com/highgroove/activities.rss.

Status Updates via Twitter

Google Group

Anatomy of a Plugin