pflux

A simple host-monitoring tool written in LFE

Introduction

pflux is built with LFE, InfluxDB, Grafana, and YAWS.

As for the name, Clojure nabbed the obvious choice for an InfluxDB client: Capacitor. Naturally, quantum mechanics was the next thought, which lead to the inexorable "probability flux" (easier to type "pflux"), a term which denotes the probability per unit time per unit area.

There you have it.

Dependencies

This project assumes that you have rebar and lfetool installed somwhere in your $PATH. If you're doing regular LFE development, you'll want to have these anyway :-)

Get the code:

    $ git clone [email protected]:lfe/pflux.git
    $ cd pflux

pflux installs LFE/Erlang dependencies automatically when you compile. Non-LFE/Erlang dependencies have separate instructions below.

If you would prefer, you can download all the dependencies explicitly with the following command:

    $ make get-deps

Screenshots

Here are some views of some ping results (3 network classifications, 8 hosts):

Configuration

ElasticSearch

• Send a PUT to http://localhost:9200/ping-stats

• Send a PUT to http://localhost:9200/ping-stats/ping-stat/_mapping with the following data in the body:

    {"ping-stat": {
       "properties": {
         "ip": {"type": "string"},
         "network": {"type": "string"},
         "latency": {"type": "float"}
         }}}

Both of these are done very easily with the Postman browser plugin for making calls to RESTful services.

InfluxDB

• Download and install InfluxDB, following the instructions.

• Load http://localhost:8083/ in your browser, connect using the default username and password (root/root) on port 8086.

• In the field under "Create Database" type "ping-stats" and then click "Create".

pflux

If you have changed the InfluxDB username or password, you'll need to update your pflux configuration data in the env section of the src/pflux.app.src file.

Once you've got your config all set, build pflux:

• make compile

You'll need to set up your servers as well. You can do this easily by starting up the LFE REPL:

    $ make shell-no-deps

Once there, you can create servers like so:

    > (pflux-app:load)
    ok
    > (pflux:store-server "google-dns" "8.8.8.8" "external" "google")
    ok
    > (pflux:store-server "router" "192.168.1.1" "wired" "internal")
    ok
    > (pflux:store-server "wifi-ap" "192.168.1.1" "wireless" "internal")
    ok

The parameters passed to store-server map, in order, to the following columns in InfluxDB:

• name
• ip
• group
• network

Admittedly the last two are named poorly (and evolved over the course of learning Grafana). The intent behind these was to provide several means of portraying different levels of granularity for server response times.You may, of course, use them however you wish :-)

With the servers created, let's do a quick sanity check:

    > (pflux:get-ips)
    ("192.168.1.1" "192.168.1.1" "8.8.8.8")

Once your servers are set up, you're ready to start the app. See the "Usage" section below for instructions.

YAWS

You shouldn't need to change anything here. Just start it up in a separate terminal window with make dev.

Grafana

• Copy the file resources/public/grafana-1.5.4/pflux-sample-config.js to resources/public/grafana-1.5.4/config.js and edit the ElasticSearch and InfluxDB sections so that the hosts match yours. If you're just loading the dashboard in a browser on the same host as pflux, you shouldn't need to make any changes.

• Open http://localhost:8080/dashboard/ in your browser.

• Get a quick start by copying this URL and pasting it in the Github gist URL when you click on the folder ("search") icon and then the "Import" link.

Usage

pflux is really used through the browser. In particular, the Grafana JS application is responsible for presenting the data collected by the LFE OTP application.

The docs for Grafana + InfluxDB aren't the best, but we were able to poke arlound for a while and get to know it without them. Some things aren't terribly intuitive (e.g., you need to single quote entires in the graph filters), but once you get used to it, things start to click and the absense of docs doesn't seem so bad.

Running

From the REPL

    $ make shell-no-deps

Then:

    > (pflux-app:start)
    #(ok <0.62.0>)

Once started, the application will immediately begin pinging the servers you added. If you load up your local InfluxDB in a browser, you can execute the following query to see that the monitoring data is indeed showing up:

    select * from ping-times

Quitting the shell will stop the application, since it was started via a manual command in the REPL. See the section "From the Command Line" for instructions on running in debug mode or as a daemon.

From the Command Line

TBD

(There's a make target for this, but the pinger currently only executes once. See ticket #10 for more info/current status.)