July 21
Andre
Hello Scout API (plus, the meaning of Life)
If you use Scout, you know its plugins are awesome: easy to use, open-source, and extremely flexible. If you need to monitor something new, just write a new plugin. If it's something other folks can use, send us pull request and we'll review it and publish it in our directory.
However, plugins aren't the only way to get data into Scout. There is also an easy API that accepts any data you can format in JSON. There are a number of good use cases for this. Maybe you have an expensive operation that you don't want to run every few minutes. Or maybe you already have a shell script, and you don't want to wrap it in Ruby as a full-blown plugin.
For this example, we'll invoke the Scout API through a once-a-day cron job. Ready?
- Click "Add a Plugin" from the server main page.
- Click "Get an API ID" on the right hand side, and confirm that you want to create a new ID. The API ID is simply a "blank" plugin -- it doesn't have any code to execute, so it passively waits for you to feed it data.
Look for the two snippets of sample code along with your ID. The first one is for using the API inside Ruby code. That is cool, but it's not what we're using right now. We're going to use the second one, which can be invoked directly from the command line:
scout_agent queue report <<< '{"meaning_of_life":42 , "plugin_id": 53601 }'
If you paste that into the command line of your server, the data will show up shortly within Scout. Go to the plugin's Raw Data page to see it, or just see it in the sidebar of your server page:
So far so good. Getting a piece of data in was very easy. We invoked scout_agent with the queue command (which can be shortened to just q if you like) and gave it a JSON string. The JSON hash had one "field" in it (meaning_of_life) plus the plugin_id.
That particular piece of data isn't going to change often. Let's move on to an actual metric -- say you want to keep tabs on the number of files in your /var/logs/ folder. From the shell, you can get that number easily: ls /var/log -1 | wc -l. My /var/log has 88 files in it right now.
Incorporating that into a scout_agent call is trivial:
scout_agent queue report <<< "{\"num_log_files\":$(ls /var/log -1 | wc -l) , \"plugin_id\": 53601 }"
And dropping it into your crontab to run once a day is also trivial (different Unix flavors have slightly different formats for crontab, so adjust accordingly):
0 0 * * * scout_agent q report <<< "{\"num_log_files\":$(ls /var/log -1 | wc -l) , \"plugin_id\": 53601 }"
There you have it! A one-liner to take a useful metric and report it to Scout once a day.
This is just scratching the surface of what's possible with the Scout API. In a future post, we'll look at using the Scout API to catch problems that might otherwise get buried in application logs.
