Plugin Development Guide

Monitoring Plugin Development Guide

The Observu server agent registers all kinds of properties, but you may want to measure even more system statistics. You can do so by developing your own monitoring plugin that runs as part of the server agent.

Perl Server Agent Plugins

Plugins can be written in Perl. As the agent itself is written in Perl, these plugins are able to store their state between intervals. This is very usefull if your metrics involve comparing values over time or need to keep a connection open.

Server Agent Plugin Example

Shown below is a very simple plugin that captures the system load. (This is one of the default server plugins, but serves as a good example)

package ObservuPlugins::SystemLoad;

# create a new plugin object
sub new {
    my $class = shift;
    my $self = {
      _config => shift,
      _state => {}
    bless $self, $class;
    return $self;

# return a hash with all produced metrics
sub produce_data{
  my($self) = @_;
  my $data = { 'load:float' => read_load() }; 
  return $data;  

# private helper method
sub read_load {
   open( my $load_in, "<", "/proc/loadavg");
   if(defined(my $load = <$load_in>)){
     if($load =~ /^([0-9\.]+)\s/){
       return 0+$1; 
   return -1;

Note that in this case the server agent plugin is named SystemLoad and resides in a file named in the ObservuPlugins directory. For your own plugin, you need another name, we strongly recommend prefixing the server agent plugin name with your company or product name.

Testing your Server Monitoring Plugin

To test your server monitoring plugin, place the file in the ObservuPlugins directory (usually /usr/local/observu/ObservuPlugins). After doing so, restart the observu server agent. On startup it should list your plugin. After a few minutes, your custom properties should show up on the monitor's reports.

Property Conventions

Properties are named hierarchically, where each level is separated by a dot. In the hash returned by your produce_data method, the keys should look like: {property_name}:{property_type}, so for example: my_plugin.object1.queue:float. This will enable the system to better understand the data provided. All allowed data types are described in the next section.

Property Datatypes

The table below lists all available property types. Providing your data with the most accurate type will provide extra hints to the system for proper reporting and representation.

Type IDNumeric repr.Base TypeDescription
string 1 String
float 2 Numeric Float
int 3 Numeric Integer
bytes 4 Numeric
seconds 5 Numeric
boolean 6 Discrete (represented as Integer)
percentage 7 Numeric
http_code 8 Discrete (represented as Integer)
error_code 9 Discrete (represented as Integer)
milliseconds 10 Numeric
kilobytes 11 Numeric
Bps 12 Numeric Bytes per second
tsv 13 Table (represented as tsv String) Table represented as a tab-seperated string
ps_tsv 14 Table (represented as tsv String) Process table represented as a tab separated string
Ops 15 Numeric Operations per second
log 16 String Chunk of logfile
har 17 Requested Page Resources
megabytes 18 Numeric

Note: The types with base type 'Discrete' are intended to be used if there is a limited set of possible values. E.g. error codes or system state. Each value can be represented by any integer, but the total number of different values should be limited per property. (Preferably at most a few dozen)

Adding Configuration Options

Although we favor auto-detection, sometimes it's more convenient to have a few configuration options in the configuration file. On creation a hash-structure with all data from the parsed configuration file is provided to each plugin.

For a configuration file like this:

KEY "mykey"
monitor_name `hostname -s`
logfile "/var/log/apache2/error.log" {
  patterns ["error", "critical"]
  property_name "logs.apache.critical"
logfile "/var/log/syslog"

The configuration hash that is passed to the plugin will look like:

  key => [
    [ "mykey" ] 
  monitor_name => [
    [ "ip-10-11-12-13" ]
  logfile => [
    [ "/var/log/apache2/error.log", {
      patterns => [
        [ ["error", "critical"]    ]
      property_name => [
        [ "logs.apache.critical"   ]
    [ "/var/log/syslog" ]

The extra array showing up in a lot of places is because each configuration rule can occur multiple times and can have multiple parameters. Parameters can be a string, array or a set or configuration rules. (Which is structured in the same way as the root configuration structure)

Final Notes

It is very important that your server monitoring plugin is fast. All plugins together need to execute within 10 seconds.