WADebug: Troubleshooting Tool for WhatsApp Business API

Current version: 0.1.5

WADebug is a command-line tool to help find any potential issues with WhatsApp Business API setup, and to make help requests from WhatsApp support more effective.

This document covers:

• Install WADebug
• Run checks
• Usage data collection and opt-out
• Retrieve logs
• Ask for help
• Changelog

Install WADebug

WADebug is a command-line tool written in Python. Install it using pip:

pip3 install wadebug

To upgrade:

pip3 install wadebug --upgrade

To uninstall:

pip3 uninstall wadebug

To validate you have wadebug installed, you can run:

wadebug --help

Run checks

WADebug has a set of actions to verify a WhatsApp Business API setup. By default, it runs all the actions available. If a problem or warning status is returned, the description, details and possible mitigation methods are shown to help you troubleshoot your setup. You will also be reminded of how to upload logs to Facebook if you need help.

To use the tool, run the following command from the machine hosting WhatsApp Business API docker containers:

wadebug

Configuration File

WADebug requires a configuration file (wadebug.conf.yml) in the current directory to run full checks.

When running wadebug without the config file, the tool will prompt to create a skeleton file for you to fill out the configuration values. If no configuration file can be found or no configuration values are set, some actions are skipped due to lack of information.

Sample configuration file:

  
    # configurations related to the MySQL database
    db:
      # hostname of the MySQL database
      host: # for example, "0.0.0.0"
      # host port that the MySQL database uses
      # to connect to database container created by docker-compose scripts, use 33060
      port: # for example, 33060
      # username to connect to the MySQL database
      user: # for example, "root"
      # password of the username that is used to connect to the MySQL database
      password: # for example, "your_database_password"

    # configurations related to WhatsApp Business API
    webapp:
      # url accessible from the host running wadebug
      baseUrl: # https://localhost:9090
      # WhatsApp Business API user account credentials to call Support API
      user: # for example, "wadebug"
      # WhatsApp Business API user account credentials to call Support API
      password: # for example, "secretdebugger"
  

Listing possible actions

To check available actions, run the following command:

wadebug ls

Partial run

To run only a subset of available actions, type this command:

wadebug partial check_software_version check_mysql_version

JSON mode

wadebug offers two modes: interactive mode and JSON mode.

Interactive mode is the default mode, when this mode is used, you are presented with visualized tables of results, notices, and prompted to create configuration file etc.
JSON mode is useful when you want to integrate wadebug into an automation pipeline to validate WhatsApp Business API setup periodically or every time you upgrade the WhatsApp Business API version for example.

To run wadebug in JSON mode, pass --json flag to any available wadebug command:

wadebug --json

Valid JSON response will be returned:

{
   "containers_status":{
      "class":"CheckContainersAreUp",
      "user_facing_name":"containers_status",
      "result":"OK"
   },
   "check_mysql_connection":{
      "class":"CheckMySQLConnection",
      "user_facing_name":"check_mysql_connection",
      "result":"OK"
   },
   "check_software_version":{
      "class":"CheckSoftwareVersion",
      "user_facing_name":"check_software_version",
      "result":"OK"
   },
   "check_mysql_version":{
      "class":"CheckMySQLVersion",
      "user_facing_name":"check_mysql_version",
      "result":"OK"
   },
   "check_network":{
      "class":"CheckNetworkAction",
      "user_facing_name":"check_network",
      "result":"OK"
   },
   "check_mysql_permissions":{
      "class":"CheckMySQLPermissions",
      "user_facing_name":"check_mysql_permissions",
      "result":"OK"
   },
   "check_mysql_password":{
      "class":"CheckMySQLPassword",
      "user_facing_name":"check_mysql_password",
      "result":"OK"
   },
   "check_db_settings_exist":{
      "class":"CheckDbSettingsExist",
      "user_facing_name":"check_db_settings_exist",
      "result":"OK"
   },
   "check_webapp_port":{
      "class":"CheckWebappPortAction",
      "user_facing_name":"check_webapp_port",
      "result":"OK"
   }
}    
    

Usage data collection and opt-out

Every time wadebug runs, usage data (including actions run and results returned) is sent to Facebook to help improve the tool as well as accelerate WhatsApp support process through Direct Support.

If you don't want to share usage data with Facebook when using the tool, run wadebug with the flag --do-not-send-usage

wadebug partial check_network --do-not-send-usage

Keep in mind that, while you will still see troubleshooting results locally, your experience interacting with our support may be degraded.

Retrieve logs

wadebug provides a convenient way to retrieve all container logs, and optionally send them to Facebook to assist our support team's investigation.

Retrieve most recent logs

To retrieve the most recent logs under wadebug_logs/ in the current directory:

wadebug logs

Important changes:

• v0.1.4 and below: wadebug logs command retrieves the last 10K lines of logs from each container
• v0.1.5 and above: wadebug logs command retrieves the latest 3 hours of logs from each container

Retrieve logs starting from a specific date time

[New since v0.1.5] To retrieve 3 hours of logs starting from a specific date time (GMT timezone), use the --since option. E.g.: the following command will retrieve logs from 2020-01-07 3:00:02 GMT to 2020-01-07 6:00:02 GMT:

wadebug logs --since='2020-01-07 3:00:02'

Send logs

To send logs to Facebook, you need to append the --send flag. You will receive a run_id as part of the response, which you can reference in Direct Support for quicker investigations. :

wadebug logs --send

wadebug logs --since='2020-01-07 3:00:02' --send

Retrieving logs from High Availability/Multiconnect setup

For High Availability/Multiconnect mode where containers are installed on one or multiple hosts, you need to log onto each host, install WADebug and run the wadebug logs commands mentioned above.

Ask for help

If you need help in troubleshooting WhatsApp Business API setup, open a Direct Support ticket with the run_id returned after you run wadebug. This allows us to see a report of the actions run and the respective results.

A report of this run has been uploaded to Facebook.  You can reference run_id (A5jedVKsdI_ZojRwL1_-MOd) in Direct Support (https://business.facebook.com/direct-support) tickets
  	

Container logs are very useful for troubleshooting, to collect and send container logs to Facebook, please run wadebug logs with the --send flag.

wadebug logs --send

and provide the run_id returned

Container logs have been uploaded to Facebook.  You can reference run_id (AcClyxkRJk3w1dEr8OAmsTn) in Direct Support (https://business.facebook.com/direct-support) tickets
  	

Change Log

January 15, 2020 (0.1.5)

• Deprecate python 2 support 🎉
• wadebug logs now gets past 3 hours logs, instead of last 10K lines of logs
• Add --since option to wadebug logs that retrieves 3 hours of logs starting from the date time value specified
• [Bug Fix] Fail fast in json mode when incompatible params are used

September 3, 2019 (v0.1.4)

• A new and cleaner UI for WADebug
• [Bug Fix] Fix wrong port printed when there's an error connecting in check_network action
• [Bug Fix] Add MySQL privilege requirements that are missing for the check_mysql_permissions action

April 26, 2019 (v0.1.3)

• Add new configuration file items required by new actions
• Add webhook health checks
• Add WADebug upgrade prompt when a new version is available on PyPi
• Add support endpoint response to uploaded logs for easier troubleshooting
• WADebug crash logs are now uploaded to to Facebook

Dec 28, 2018 (v0.1.2)

• Limit the size of logs retrieved
• Capture coreapp coredumps in case of crashes
• Add new command to retrieve logs without upload
• Add enum34 as a required module for < Python 3.4

Oct 23, 2018 (v0.1.1)

• Initial release