Moonitor

Moonitor is a monitoring tool that collects information from a list of configured hosts and saves this information in a time series database.

It's designed on top of the Akka framework. As such, it's modeled as actors and message passing between them.

Its fundamental architecture is based on agents and principals. Agents are installed on the target machines to be monitored. Principals tell agents what information to collect and how often. Then, agents start collecting and sending the information to their respective principals. Finally, principals save the information to the database.

Technology stack: Principals, agents and other auxiliar actors are written in Scala. To collect machine metrics, the Sigar library is used. Agents configuration (where and what to collect) is saved in a Redis instance. Metric values are stored into an InfluxDB database. Optionally, a Grafana server can be added to visualize graphics from InfluxDb data.

Other technologies involved: Spray for the REST services. Jackson for JSON serialization. Typesafe config for environmental configurations. Courier for sending email notifications. Scalaj for http communication with InfluxDb. SBT as the building tool. sbt-native-packager to easily create installation packages.

Building and running

Requirements

In order to build and run this project as is, you need Java 8 and sbt. The Java 8 requirement is due to the Typesafe Config library version. If you want to use Java 7, downgrade the config library version with the property defined in build.sbt here.

If you just want to run a single instance from sbt, execute run from the specific subproject you want to run. For example:

$ sbt
> project agent
> run

On the other hand, if you want to test the scripts generated by sbt-package-manager, you can execute stage from a subproject. Then you can call the script directly. For instance:

$ sbt "project agent" stage
$ ./agent/target/universal/stage/bin/moonitor-agent

Installation

In order to install the agent or the principal as OS services, an easy way is to use sbt-native-packager with the JavaServerAppPackaging plugin. To do this, just run rpm:packageBin or debian:packageBin from the corresponding subproject, depending on the target platform. For example, to generate the agent's rpm package:

$ sbt
> project agent
> rpm:packageBin

Then the target .rpm file will be: agent/target/rpm/RPMS/x86_64/moonitor-agent-0.1-1.x86_64.rpm. And you can install it with the following command:

$ sudo rpm -i moonitor-agent-0.1-1.x86_64.rpm

If you chose debian, the .deb file will be: agent/target/moonitor-agent_0.1_all.deb. To install it in a debian system:

$ sudo dpkg -i moonitor-agent_0.1_all.deb

The installation of these packages will create the corresponding file structure (see documentation), and add it as a system service. You cant start and stop the service by issuing sudo service moonitor-agent start and sudo service moonitor-agent stop respectively.

To install the principal, the process is the same. Just be aware that you'll have to install an InfluxDb instance somewhere and configure the principal to save the metrics there. By default, the principal will try localhost port 8086, as is the default InfluxDb installation. See InfluxDb documentation on how to install.

Environment configuration

Both the agent and the principal provide environment customizable configurations. To change a property's default value, create a file in /etc/default/moonitor-agent.conf or /etc/default/moonitor-principal.conf.

These are the default values for the principal:

agent {
  system_name = "agent-system"
  port = 2552
  protocol = "akka.tcp"
}

restservice {
  iface = "localhost"
  port = 8080
}

influxdb {
  write_url = "http://localhost:8086/write"
}

smtp {
  host = smtp.gmail.com
  port = 587
  auth = true
  use_tls = true
}

And the only configuration for the agent is where to find the collection strategies:

plugins.dir = "/usr/lib"

Hosts configuration

The principal provides a REST service to configure hosts, the metrics to be collected and alerts.

To add a new host, POST to <principal_domain>:<port>/hosts/<new_host_name>.

To stop all metrics collection and remove the configuration for a host, DELETE to <principal_domain>:<port>/hosts/<host_to_delete>.

To start collecting a new metric in a host, PUT to <principal_domain>:<port>/hosts/<host_name>/metrics with a Json representation of the metric configuration.

To stop collecting a metric in a host, DELETE to <principal_domain>:<port>/hosts/<host_name>/metricswith a Json representation of the metric id.

To create an alert for a host, PUT to <principal_domain>:<port>/hosts/<host_name>/alerts with a Json representation of the alert configuration.

To remove an alert configuration, DELETE to <principal_domain>:<port>/hosts/<host_name>/alerts with a Json representation of the metric id.

Metric id Json example:

{
  "packageName":"com.mooveit.moonitor.collector.strategies",
  "className":"FreeSpaceStrategy",
  "metricName":"free_space_strategy",
  "params":"/"
}

Metric configuration Json example:

{
  "packageName":"",
  "metricId":<metric_id>,
  "frequency":30000
}

Alert configuration Json example:

{
  "metricId":<metric_id>,
  "operator":"com.mooveit.moonitor.domain.alerts.Gt",
  "value":15,
  "mailTo":"some.mail@example.com"
}

Visualization

To quickly and easily visualize the data from InfluxDb, you can use Grafana, which comes with InfluxDb support out-of-the-box. See Grafana documentation on how to install and configure. Important: the principal will automatically create a new InfluxDb database for each configured host. For instance, if you configure the host 192.168.1.2 then you will find a database called metrics-192.168.1.2.

License

See the LICENSE file for license rights and limitations.