Monitoring OS X Servers with Observium – Part 2: the Observium Agent

If you missed Part 1 (setting up the SNMP daemon), click here to read it!

I know not many shops use OS X servers any more, but we do – so here’s a how to on getting Observium to draw pretty, pretty graphs of your Apple boxes. This guide applies to both the Community and Professional editions.

Note: I’m going to do this walk through assuming you are running OS X 10.11 “El Capitan.” 10.11 has a feature called System Integrity Protection – tl;dr it means we can’t write to /usr/bin/ or /usr/lib. The instructions below will work just fine for any version of OS X before 10.11, there are just a few steps that are slightly extraneous.

In this post I will detail how to set up the Observium Agent, which is a little script that sits on your system and passes additional information from your servers back to Observium. This makes it easy to monitor services that don’t come with SNMP integration without needing a ton of really awful modifications to your system.

You’ll need to grab the latest version of Observium from source. If you’re using the Community edition, this is the tarball download from the website. If you’re using Professional, you can grab from SVN. Open up a terminal and change directories to the Observium source directory. Copy the agent script and make it executable, and create the local folder for agent scripts:

sudo cp scripts/observium_agent /usr/local/bin/
sudo chmod +x /usr/local/bin/observium_agent
sudo mkdir -p /usr/local/lib/observium_agent/local

This will set up the system to be able to execute the agent script itself. The second part of the agent script is the contents of the ‘local’ folder we created – this is where the agent looks to extend the service data it passes back. Let’s make one tweak to the agent script to jibe with OS X, though – open it up in your favorite text editor:

sudo vim /usr/local/bin/observium_agent

You’ll need to change the line that reads:

export AGENT_LIBDIR="/usr/lib/observium_agent"

to be this instead:

export AGENT_LIBDIR="/usr/local/lib/observium_agent"

Save the changes and close your text editor.

Now we can set up the scripts we want to use to monitor various system processes. These are located in the Observium source code directory under scripts/agent-local. I’ll cover setting up PGSql, MySQL, and Apache scripts in the next part of the series, but if you want to play around with these on your own then you can copy them to the local folder now.

Finally, we need to set the server to listen for the Observium server’s calls to the agent port. On linux, this is generally done with xinetd – on OS X, we’ll use the native launchd.

Save the following plist file as org.observium.agent.plist in the /Library/LaunchDaemons directory:

You can then load the launchd job:

sudo launchctl load /Library/LaunchDaemons/org.observium.agent.plist

To test, open up a terminal and use telnet (yep, telnet!):

telnet your.server.hostname 36602

It should spit back a bunch of output like this:
[ rickheil@rick-heil ~ ]$ telnet your.server.hostname 36602
Connected to your.server.hostname.
Escape character is '^]'.
Version: 1.0.1
AgentOS: linux
PluginsDirectory: /usr/lib/observium_agent/plugins
LocalDirectory: /usr/lib/observium_agent/local
AgentDirectory: /etc/observium
Connection closed by foreign host.

You’ll notice that this will work from any IP address. You should use your firewall software of choice to restrict access to port 36602 to only be from your Observium server.

Finally, let’s make sure Observium knows the agent is active on your server – on the Observium page for the device under properties, go to Modules and ensure “unix-agent” is enabled. Wait for your next poll and that’s it!


In the next post, I’ll cover getting external applications set up with the Observium agent.