Set Up Dashboard to Monitor the WhatsApp Business API Client

Starting with v2.21.3, the /metrics and /v1/stats endpoints allow for exporting internal metrics in the Prometheus text format. Information about how to access the raw data can be found in the Stats and Metrics documentation.

In addition to being able to access the raw data through the API, starting with release v2.21.3 a dashboard can be set up using Docker Compose and the provided YAML file (monitoring-compose.yml and host-exporter-compose.yml) to help simplify the task of monitoring an instance of the WhatsApp Business API.

Overview

Instance Monitoring

The monitoring-compose.yml file is used to start up the following three containers on the monitoring host. These containers should be hosted separately from the machine(s) that are hosting the running Webapp and Coreapp containers. Hosting them separately mitigates any potential performance impact resulting from processing the metric data.

• Prometheus — For collecting and storing metrics from Webapp instances and various metric exporters
  • Requires the WA_WEB_ENDPOINT, WA_WEB_USERNAME, and WA_WEB_PASSWORD environmental variables to pull Webapp and Coreapp metrics from the WebApp instance through the /metrics and /v1/stats endpoints.
  • Requires the WA_CORE_ENDPOINT environmental variable to pull machine and container metrics from the node-exporter and cadvisor containers on the CoreApp host(s). For High Availability/Multiconnect setups, Prometheus will periodically query the /v1/health endpoint to automatically discover Master and Coreapp hosts to pull metrics from. Please ensure the node-exporter and cadvisor ports on the CoreApp host(s) match the values of the WA_NODE_EXPORTER_PORT and WA_CADVISOR_PORT environmental variables in the monitoring-compose.yml file.
  • Requires the WA_DB_HOSTNAME environmental variable to pull machine metrics from the node-exporter instance on the database host. Please ensure the node-exporter port on the database host matches the WA_DB_NODE_EXPORTER_ENDPOINT environmental variable in the monitoring-compose.yml file.
• Grafana — For presenting dashboards based on the Prometheus data
  • Requires the GF_SECURITY_ADMIN_PASSWORD environmental variable to set up a password for the admin account in Grafana.
• mysqld-exporter — For collecting MySQL internal stats and exposing the /metrics endpoint for Prometheus
  • Requires the WA_DB_USERNAME, WA_DB_USERNAME, WA_DB_PASSWORD, WA_DB_HOSTNAME, and WA_DB_PORT environmental variables to connect to the MySQL instance.

The host-exporter-compose.yml file is used to start up two exporter containers on the CoreApp host and the database host:

• cadvisor — For collecting resource usage and performance characteristics of running containers on the installed host and exposing the /metrics endpoint to Prometheus
• node-exporter — For collecting machine metrics of installed host and exposing the /metrics endpoint to Prometheus

Prerequisites

Before the monitoring containers can be set up, the following steps need to happen:

1. Both the Webapp and Coreapp containers must be installed and running.
2. The system that will host the monitoring containers must have Docker Compose installed.
3. Clone all files from the monitoring directory of the WhatsApp-Business-API-Setup-Scripts Github repo.

Setup

1. In the same directory that contains monitoring-compose.yml, create a file called .env.
2. Add the following environment variables to this .env file:
   • WA_WEB_ENDPOINT=your-webapp-hostname:your-webapp-port
   • WA_WEB_USERNAME=your-username
   • WA_WEB_PASSWORD=your-password
   • WA_CORE_ENDPOINT=your-coreapp-hostname
   • WA_DB_HOSTNAME=your-database-hostname
   • WA_DB_PORT=your-database-port
   • WA_DB_USERNAME=your-database-username
   • WA_DB_PASSWORD=your-database-password
   • GF_SECURITY_ADMIN_PASSWORD=your-grafana-admin-password
   Note:
   • WA_WEB_ENDPOINT points to a running Webapp container and must be reachable from the machine that will host the monitoring containers.
   • WA_DB_HOSTNAME points to the MySQL server hosting the backing datastore for the WhatsApp Business API Client and must be reachable from the machine that will host the monitoring containers.
   • If you wish to host everything on the same server, change Prometheus's ports from 9090:9090 to 9091:9090 and access http://your-monitoring-hostname:9091/targets instead.
   • For a High Availability/Multiconnect setup — All machines running Master and Coreapp containers must be reachable from the machine that will host the monitoring containers.
3. Run the following code to start the Prometheus, Grafana, and mysqld-exporter containers on the monitoring host:

   docker-compose -f monitoring-compose.yml up -d
   

4. (Optional if you have your own machine metric monitoring) Run the following code to start the node-exporter and cadvisor containers on every Coreapp host:

   scp host-exporter-compose.yml your-coreapp-hostname
   docker-compose -f host-exporter-compose.yml up -d
   

5. (Optional if you have your own machine metric monitoring) Run the following code to start node-exporter on the database host:

   scp host-exporter-compose.yml your-database-hostname
   docker-compose -f host-exporter-compose.yml up -d node-exporter
   

6. Accessing http://your-monitoring-hostname:9090/targets from a browser should load a webpage displaying the endpoints that are up and running. In the following example you can see WA_WEB_ENDPOINT=192.168.57.100:9090, WA_CORE_ENDPOINT=192.168.57.100 and WA_DB_HOSTNAME=192.168.56.100.
   

   Targets
7. Accessing http://your-monitoring-hostname:3000/d/whatsapp/biz-clients will load the Grafana dashboard for the system.
   

   Grafana Dashboard

   The username is admin and the password is your-grafana-admin-password.

   You can check out other dashboards by clicking Tag Biz, System, and Database.
8. Set up notification channels to receive alerts.

Upgrading

It's highly recommended you run the same version of monitoring containers for the WhatsApp Business API Webapp and Coreapp containers.

The monitoring-compose.yml file has fields indicating container versions, for example:

services:
  ...
  prometheus:
      image: docker.whatsapp.biz/prometheus:v2.21.4
  ...
  grafana:
      image: docker.whatsapp.biz/grafana:v2.21.4

To upgrade an installation, change the version numbers in the monitoring-compose.yml file:

services:
  ...
  prometheus:
      image: docker.whatsapp.biz/prometheus:v2.21.6
  ...
  grafana:
      image: docker.whatsapp.biz/grafana:v2.21.6

Then, uninstall and restart the Docker containers:

docker-compose -f monitoring-compose.yml down
docker-compose -f monitoring-compose.yml up -d

Troubleshooting Logs

To obtain logs for troubleshooting, run the following command:

docker-compose -f monitoring-compose.yml logs > debug_monitoring_output.txt
  
# On Coreapp host or database host
docker-compose -f host-exporter-compose.yml logs > debug_host_exporter_output.txt

You can then send those files to WhatsApp for analysis and debugging.

Uninstalling

When you no longer wish to gather metrics, you can stop monitoring and remove the containers with the following code:

docker-compose -f monitoring-compose.yml down
  
# On Coreapp host or database host
docker-compose -f host-exporter-compose.yml down

Uninstall containers and remove volumes with the following code:

docker-compose -f monitoring-compose.yml down -v
  
# On Coreapp host or database host
docker-compose -f host-exporter-compose.yml down -v

Learn More

• Monitoring Notifications
• Monitoring Alerts