Using AIS-catcher with Grafana and Prometheus¶

Grafana is an analytics platform that can provide alternative graphs for AIS-catcher.

In this guide we will be using Prometheus as the data repository.

Using Grafana and Prometheus in this configuration does not require a plan, account, or credentials for their respective cloud offerings.

Hardware requirements¶

Prometheus will store a lot of data, and Grafana will do a lot of data queries. As a result, it would be better if you run these programs on a different system than your feeder Raspberry Pi. This will leave your Pi focused on data collection and processing, and unbothered by the CPU and Disk IO load that Prometheus/Grafana will cause.

You can do it on a single system. We're assuming below that you are not.

Step 1: Make Prometheus data available for AIS-catcher¶

Edit your AIS-catcher's command line and ensure that PROME on is included after the -N <port> directive. For example:

AIS-catcher -N 8100 PROME on

Step 2: create a container stack for `prometheus` and `grafana`¶

You can skip this if you already have Prometheus and Grafana installed.

The example wil use a containerized (Docker) installation of Prometheus and Grafana. If you need to install Docker, please do so first. For a quick and painless way to get started, we suggest that you use this install script.

On the machine where you will run Prometheus and Grafana, create a docker-compose file in the /opt/grafana directory:

sudo mkdir -p -m777 /opt/grafana/grafana/appdata /opt/grafana/prometheus/config /opt/grafana/prometheus/data
cd /opt/grafana
cat > docker-compose.yml

Now paste in the following text *):

<‐‐ Click the arrow to see the docker-compose.yml text

version: '3.9'

volumes:
  grafana:
    driver: local
    driver_opts:
      type: none
      device: "/opt/grafana/grafana/appdata"
      o: bind
  prom-config:
    driver: local
    driver_opts:
      type: none
      device: "/opt/grafana/prometheus/config"
      o: bind
  prom-data:
    driver: local
    driver_opts:
      type: none
      device: "/opt/grafana/prometheus/data"
      o: bind

services:
  grafana:
    image: grafana/grafana-oss:latest
    restart: unless-stopped
    container_name: grafana
    hostname: grafana
    tty: true
    # uncomment the following section and set the variables if you are exposing Grafana to the internet behind a rev web proxy:
    environment:
    # snuids-radar-panel plugin is needed for polar plots:
      - GF_INSTALL_PLUGINS=snuids-radar-panel
    # uncomment and set the following variables if you are exposing Grafana to the internet behind a rev web proxy:
    #   - GF_SERVER_ROOT_URL=https://mywebsite.com/grafana/
    #   - GF_SERVER_SERVE_FROM_SUB_PATH=true
    ports:
      - 3000:3000
    volumes:
      - grafana:/var/lib/grafana

  prometheus:
    image: prom/prometheus
    container_name: prometheus
    hostname: prometheus
    restart: unless-stopped
    tmpfs:
      - /tmp
    volumes:
      - prom-config:/etc/prometheus
      - prom-data:/prometheus
    ports:
      - 9090:9090

*) The volume definition structure is written this way purposely to ensure that the containers can place files in the persistent directories. Do not try to "directly" map volumes (/opt/grafana/grafana/appdata:/var/lib/grafana).

Download and create Grafana and Prometheus for the first time with this command:

docker compose up -d

You should now be able to see the following directories:

/opt/grafana/grafana/appdata
/opt/grafana/prometheus/config
/opt/grafana/prometheus/data

Step 3: Configuring Prometheus¶

Prometheus needs to be told where to look for the data from AIS-catcher. We will create a target prometheus configuration file that does this, please copy and paste the following. Make sure to replace ip_of_AIS-catcher_machine:8100 with the IP address or hostname of the machine and the web port where AIS-catcher is running:

docker exec -it prometheus sh -c "echo -e \"  - job_name: 'ais'\n    static_configs:\n      - targets: ['ip_of_AIS-catcher_machine:8100']\" >> /etc/prometheus/prometheus.yml"
docker restart prometheus

(If you screw this up, do NOT re-run the command. Instead, try sudo nano /opt/grafana/prometheus/config/prometheus.yml and fix it that way.)

Accessing Prometheus and Grafana via your browser¶

You should be able to point your web browser at:

http://docker.host.ip.addr:9090/ to access the prometheus console.
http://docker.host.ip.addr:3000/ to access the grafana console, use admin/admin as initial credentials, you should be prompted to change the password on first login.

Remember to change docker.host.ip.addr to the IP address of the machine where Prometheus and Grafana are located.

Configuring data source and dashboard in Grafana¶

After you have logged into the grafana console the following manual steps are required to connect to prometheus as the data source. You must do this even if you are already connected to Prometheus for other purposes (such as for getting readsb/ultrafeeder/tar1090 data)

In Grafana, click Configuration (cogwheel) -> Data Sources
Click Add a new data source in the main panel
Click Prometheus from the list of options provided
Input or select the following options, if the option is not listed, do not input anything for that option: