Troubleshooting
This section addresses the most common issues related to the installation and configuration of the Gateway Agent components.
Where can I find the Gateway Agent log files?
Logs are stored individually for each Gateway Agent component. For most components, they are stored in syslog. To view them, use the journalctl
command. For example, to view logs of the Modbus Protocol Adapter, use:
journalctl -u gwa-modbus-adapter-c
To copy logs to a log file, use:
journalctl -u gwa-modbus-adapter-c > gwa-modbus-adapter-c.log
How to change the log level of the Gateway Agent components?
There are seven levels of log verbosity that you can set for the Gateway Agent components. The default log level is 2 (INFO). For this level, the Gateway Agent only logs information of INFO, WARNING, ERROR, and CRITICAL types.
To set a different level, edit the /etc/default/gwa-<component-name>
file. For example, for the Modbus Protocol Adapter, the file is
/etc/default/gwa-modbus-adapter-c
, and for the Rule Engine it is /etc/default/gwa-rule-engine-cpp
. For a full list of component names, see the Components and Packages Names section.
The file contains a list of available log verbosity levels and the GWA_LOG_VERBOSITY
option, where you set the log level for a given component. To get the most detailed logs, set it to 0
. To disable the logging, set it to 6
.
Example:
# Set appropriate log verbosity level:
# LEVEL_OFF = 6
# LEVEL_CRITICAL = 5
# LEVEL_ERROR = 4
# LEVEL_WARN = 3
# LEVEL_INFO = 2
# LEVEL_DEBUG = 1
# LEVEL_TRACE = 0
#
GWA_LOG_VERBOSITY=2
Where can I find the Gateway Agent configuration files?
Configuration files for each component are stored as .json
files in the /etc/relayr/<component_name>
folder. For information on the component names, see the Components and Packages Names section.
How to check which Gateway Agent components are installed and what their status is?
There are several methods of checking the status of the installed Gateway Agent components.
If you have the Configuration Manager installed, you can use its graphical interface to view a list of the installed Gateway Agent components and their status. See here for details on the components list.
Alternatively, you can also use one of the commands listed below.
Depending on your operating system and its version, some of the commands might not be supported.
You can check the components' status using the systemctl
command:
systemctl list-unit-files | grep gwa
You can also use one of these commands to list the running components:
ps aux | grep gwa
or:
dpkg -l | grep gwa
You can also check the components' status using the health monitoring mechanism. To do so, run the following command and wait about a minute to view the components' status:
mosquitto_sub -t "v1/services/#" -v
How do I know which version of the Gateway Agent components is installed?
If you have installed or upgraded the Gateway Agent components and want to know which component version is installed, run the following command:
sudo apt list gwa-*
Alternatively, you can use this command:
dpkg -l | grep gwa
The installed components are then listed together with their version.
If you have the Configuration Manager installed, you can use its graphical interface to view the list of the installed Gateway Agent components and their version. See here for details on the components list.
How can I check if there are any updates available for the installed Gateway Agent components?
To check for updates and upgrade the relayr Gateway Agent components on Debian or Ubuntu Linux, follow the steps described below.
It is assumed that the Gateway Agent repository is already configured in your system. If not, see the Installation Guide section for the installation procedure.
For more information on the upgrade recommendation, see the Upgrading Gateway Agent section.
- Update the package list:
sudo apt-get update
- Check for updates:
sudo apt list --upgradable gwa-*
- Upgrade the selected packages:
sudo apt-get install <package_name>
Here is an example how to upgrade the Modbus Protocol Adapter:
sudo apt-get install gwa-modbus-adapter-c
- Verify the upgrade by checking the component versions:
sudo apt list gwa-*`
Here is an example of the output:
Listing... Done
gwa-modbus-adapter-c/stable 1.0.0-1~stretch armhf
gwa-relayr-cloud-v2-adapter-c/stable 1.0.0-1~stretch armhf
How do I monitor the messages exchanged between the Gateway Agent components?
You can monitor both the Southbound and Northbound Interface by using the
mosquitto_sub
command.
To do so, you first have to install the mosquitto clients with the following command:
sudo apt-get install mosquitto-clients
- Run the following command to monitor the Southbound MQTT interface:
mosquitto_sub -v -t "v1/sb/#"
- Run the following command to monitor the Northbound MQTT interface:
mosquitto_sub -v -t "v1/nb/#"`
Where can I find more information on the data exchanged between the Gateway Agent components?
For details, refer to the API documentation.
How can I collect key information about the Gateway Agent installation and environment?
For troubleshooting and support purposes, you can use the gwa-troubleshoot.lua
data collection script, which collects information about the operating system, the hardware, the installed Gateway Agent components and their configuration files and logs. The script publishes the gathered data to the relayr Cloud Blob Storage as a .zip
archive. For more information how to use the script, see the Data Collection Script section.