Using Collectd And Dump1090-Tools To Monitor Dump1090-mutability

First off this walkthrough is meant for those interested in manually setting up performance graphs for their ADS-B receiver running dump1090-mutability using the same author's dump1090-tools. If you are looking for a more less involved approch to setting up graphs for your receiver xforce30164 on the planefinder forums has created a great bash script you can download and run which automates this entire process on a Raspberry Pi however I am not sure how well this script works on Debian or Ubuntu.

DO NOT SIMPLY COPY AND PASTE AND NOT READ THROUGH THIS DOCUMENTATION!
Skimming through this documentation without reading will 99.99999 percent of the time result in a broken setup.

If you are ready to begin manually setting up and configuring dump1090-tools let us begin first by installing the packages which will be required in order to complete these steps.

sudo apt-get update
sudo apt-get install rrdtool collectd lighttpd

Now lets create our build environment and download dump1090-tools as well as place some initial items where they belong.

mkdir ~/build
cd ~/build
git clone https://github.com/mutability/dump1090-tools.git
sudo service collectd stop
sudo mv /etc/collectd/collectd.conf /etc/collectd/collectd.conf.back
sudo cp ~/build/dump1090-tools/collectd/collectd.conf.example /etc/collectd/collectd.conf
sudo mkdir /var/www/html/collectd

We will now need to make some changes to the copied version of collectd.conf. Open the file /etc/collectd/collectd.conf in your favorite text editor.

sudo nano /etc/collectd/collectd.conf

The first change we will need to make is change the Hostname variable to the name of your machine or localhost.

Hostname "localhost"

For some reason an important piece of the conifguration was left out of this file. You will need to add the following Lines to this file before or after the logging plugin configuration. Without these lines the .rrd databases storing the history for these charts will not be created.

LoadPlugin rrdtool
<Plugin rrdtool>
        DataDir "/var/lib/collectd/rrd"
</Plugin>

Now the TypesDB path will need to be changed. Change this path to your home directory plus the path to where we cloned the dump1090-tools repository. If you followed these directions on a Raspberry Pi logged in as the user pi the path will generally need to be changed to the following.

Load the dump1090 types:
TypesDB "/home/pi/build/dump1090-tools/dump1090.db"

Next we will need to configure the dump1090 python module located further down this file. You will need to change the ModulePath to the path to the collectd folder located in the folder containing the repository you cloned earlier. Then you will need to replace the default Instances to one pointing to your instance of dump1090. You should end up with a section looking somewhat like the following. Once you are done with these edits go ahead and save the file.

<Plugin python>
        ModulePath "/home/pi/build/dump1090-tools/collectd"
        LogTraces true
        Import "dump1090"
        <Module dump1090>
                <Instance localhost>
                        URL "http://localhost/dump1090"
                </Instance>>
        </Module>
</Plugin>

Now we will need to focus our attention on creating a working make-graphs.sh script. First lets copy the example which has been supplied to us and begin there.

cp ~/build/dump1090-tools/collectd/make-collectd-graphs.sh ~/build/dump1090-tools/collectd/make-graphs.sh

Open the file make-graphs.sh in your favorite text editor.

nano ~/build/dump1090-tools/collectd/make-graphs.sh

In the latest versions of Raspian, Debian, and Ubuntu the default folder for Lighttpd's www root directory changed from /var/www/ to /var/www/html. That being said this walkthrough uses /var/www/html to remain compatable with other walkthroughs posted on this site. If the root www directory on your system for lighthttpd is located somewhere other than /var/www then you will need to change the path in the following lines to reflect the new path. If Lighttpd's www root directory on your machine is /var/www you can safely skip this edit and move to the next. The strongly typed text in the next line is an example of where the path change will be needed if the www root directory differs from /var/www.

aircraft_graph /var/www/collectd/dump1090-$2-acs-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"

common_graphs() {
  aircraft_graph /var/www/html/collectd/dump1090-$2-acs-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
  cpu_graph /var/www/html/collectd/dump1090-$2-cpu-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
  tracks_graph /var/www/html/collectd/dump1090-$2-tracks-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
}

# receiver_graphs host shortname longname period step
receiver_graphs() {
  common_graphs "$1" "$2" "$3" "$4" "$5"
  signal_graph /var/www/html/collectd/dump1090-$2-signal-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
  local_rate_graph /var/www/html/collectd/dump1090-$2-rate-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
}

hub_graphs() {
  common_graphs "$1" "$2" "$3" "$4" "$5"
  remote_rate_graph /var/www/html/collectd/dump1090-$2-rate-$4.png /var/lib/collectd/rrd/$1/dump1090-$2 "$3" "$4" "$5"
}

Now lets change the last four lines of this file so that graphs are created for the dump1090 reciever running locally on this machine. Replace the last four lines with the following lines. Again make sure the path to Lighttpd's root www directory is correct.

receiver_graphs localhost localhost "ADS-B Receiver" "$period" "$step"
#hub_graphs localhost hub "ADS-B Hub" "$period" "$step"
machine_cpu_graph /var/www/html/collectd/machine-cpu-$period.png /var/lib/collectd/rrd/localhost/cpu-0 "Machine" "$period" "$step"

Notice the hub_graphs line is commented out since that aspect will not be covered in this article. I left this line here for future reference if at some point you are running multiple instances of dump1090 and wish to display information pertaining specifically to the dump1090 instance used as a hub.

Once done with your edits make the make-graphs.sh file executable.

chmod +x ~/build/dump1090-tools/collectd/make-graphs.sh

Now that collectd is configured and our script which will be used to create the graphs has been created we will need to start the collectd service and edit the root users crontab in order to facilitate the running of the make-graphs.sh script at regular intervals.

sudo service collectd start
sudo su
crontab -e

Once the crontab file is opened and ready to be edited add the following lines to it after which you will need to save it. Be sure to modify the paths specified to reflect the locations of files on your setup.

*/5 * * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 1h >/dev/null
*/10 * * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 6h >/dev/null
2,12,22,32,42,52 * * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 24h >/dev/null
4,24,44 * * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 7d >/dev/null
6 * * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 30d >/dev/null
8 */12 * * * sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 365d >/dev/null

After editing the root users crontab go ahead and log out as root and return to using your own login.

exit

Now that collectd is configured and our make-graphs.sh script is scheduled to run at the appropriate times you will need to create an HTML page which will display the graphs within a web browser. The HTML given here is an example of the basics needed to display the graphs so feel free to add to this HTML as you see fit. Create the file /var/www/html/index.html in your favorite text editor.

sudo nano /var/www/html/collectd/index.html

Add the following HTML to this file and save it.

<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="60">
    <meta http-equiv="cache-control" content="no-cache" />
    <title>ADB-S Receiver Graphs</title>
  </head>
  <body>
    <h1>ADS-B Receiver Graphs</h1>
    <p>
      <a href="#" onclick="switchView('1h')">[ 1 Hour ]</a>
      <a href="#" onclick="switchView('6h')">[ 6 Hour ]</a>
      <a href="#" onclick="switchView('24h')">[ Day ]</a>
      <a href="#" onclick="switchView('7d')">[ Week ]</a>
      <a href="#" onclick="switchView('30d')">[ Month ]</a>
      <a href="#" onclick="switchView('365d')">[ Year ]</a>
    </p>
    <div>
      <img id="rate" src="dump1090-localhost-acs-1h.png">
    </div>
    <div>
      <img id="rate" src="dump1090-localhost-cpu-1h.png">
    </div>
    <div>
      <img id="rate" src="dump1090-localhost-tracks-1h.png">
    </div>
    <div>
      <img id="rate" src="dump1090-localhost-signal-1h.png">
    </div>
    <div>
      <img id="rate" src="dump1090-localhost-rate-1h.png">
    </div>
    <div>
      <img id="rate" src="machine-cpu-1h.png">
    </div>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
    <script type="text/javascript">
      function switchView(time_name){
        $("#adsb-message-trailing").attr("src", "dump1090-localhost-acs-" + time_name + ".png");
        $("#adsb-message-rate").attr("src", "dump1090-localhost-cpu-" + time_name + ".png");
        $("#adsb-aircraft-seen").attr("src", "dump1090-localhost-tracks-" + time_name + ".png");
        $("#adsb-aircraft-tracks").attr("src", "dump1090-localhost-signal-" + time_name + ".png");
        $("#adsb-max-range").attr("src", "dump1090-localhost-rate-" + time_name + ".png");
        $("#adsb-signal-strength").attr("src", "machine-cpu-" + time_name + ".png");
      }
    </script>
  </body>
</html>

Now that everything is set up run the following command to generate the 1 hour graphs.

sudo /home/pi/build/dump1090-tools/collectd/make-graphs.sh 1h

To view your graphs open a web browser and visit the address http://<YOUR-RECEIVERS-IP-ADDRESS>/collectd/. Keep in mind some graphs may not be visible right away rest assured if everything is working OK and you see the one hour graphs the other graphs should appear as the jobs added to root's crontab are executed at their scheduled intervals.