Highlighted
Posted by TeamViewer Staff
TeamViewer Staff

Start monitoring your IoT Network Bandwidth

This article applies to all TeamViewer IoT users who wants to measure their Network Bandwidth.

Description

The TeamViewer IoT Bandwidth Monitor (BWM) allows you to monitor your network interface Input/output traffic speed (B/sec) for any existing network interface in the Unix-like (*nix) operating systems.  This guide will allow you to integrate the BWM with the TeamViewer IoT Agent.

Step 1 - Install dependencies

The BWM requires the following to be installed on the device:

  • TeamViewer IoT Agent v 1.1.12 or greater
    • For details, reference: https://teamviewer-iot.com/
    • To identify the installed version, run the following command: (an error, or no result, indicates an older version of the agent is installed)
      sudo teamviewer-iot-agent info

Step 2 - Download the Bandwidth Monitor

  • From your device running the TeamViewer IoT Agent, download the connector: 
wget https://download.teamviewer-iot.com/connectors/teamviewer-iot-bandwidth-monitor/1.0.0/teamviewer_iot_bandwidth_monitor-1.0.0.sh
  • Upon download completion, copy the file into the TeamViewer IoT Monitoring directory
sudo mkdir -p /usr/local/teamviewer-iot-agent/monitoring/
sudo cp -p teamviewer_iot_bandwidth_monitor-1.0.0.sh /usr/local/teamviewer-iot-agent/monitoring/

Step 3 - Integrate the BWM with the TeamViewer IoT Agent 

The TeamViewer IoT Agent includes its own system monitoring configuration file.  This configuration file will be extended to include the Bandwidth Monitor.  As you are going to manually edit a system configuration file, ensure to create a backup of the file in the case the file gets corrupted by user error.

  1. Open for editing the TeamViewer IoT Agent monitoring configuration file located at:
    • /var/lib/teamviewer-iot-agent/system_monitors.conf
    • sensors are hosted under the "sensors" node of the configuration file
  2. For the network interface you want to monitor, append its information to the configuration file.  Reference the template below and replace the placeholders with your network interface details.
    • Monitoring of multiple network interfaces will be supported in future versions.
  3. Save the configuration file.
  4. Restart the agent to reload the configuration file.
    • teamviewer-iot-agent restart
  5.  Log into your TeamViewer IoT dashboard and verify that the Sensors/Metrics added to the configuration file now appear on your Metrics tab.
    • Pin the metrics to your dashboard and ensure the data is being updated per the frequency specified in the config file

Bandwidth Monitor Template

Use the following template to add your network interface details to the monitoring configuration file.  Ensure to replace the following placeholders with the specifics of each of your network interfaces:

  • Note: the monitoringService parameters identifies the path of the connector installed in Step 1.  Ensure the path you installed the connector matches the path specified here
  • monitoringParams - network interface to monitor (e.g. eth0)
  • metrics - name, key, valueType, valueAnnotation
    • Note:
      • the metric name should identify the network interface & type of traffic to monitor
      • key should be either "InputTraffic" or "OutputTraffic"
      • other parameters should not be changed

More details about the JSON schema can be found in the Custom Plugin Connector article.

{
  "sensors":[
    {
      "name":"bandwidth",
      "frequency":300,
      "monitoringService": "/usr/local/teamviewer-iot-agent/monitoring/bandwidth/bandwidth.sh ",
      "monitoringParams":"-i eth0",
      "metrics":[
        {
          "name":"eth0_Input",
          "key":"InputTraffic",
          "valueType":"integer",
          "valueAnnotation":"bytes"
        },
        {
          "name":"eth0_Output",
          "key":"OutputTraffic",
          "valueType":"integer",
          "valueAnnotation":"bytes"
        }
      ]
    }

Notes

The BWM tries to use several methods to measure network traffic.  At least one of the methods identified below must be available for the BWM to execute properly.

  1. The file '/proc/net/dev' contains statistics about network interfaces and their used traffic. It accumulates many statistics, but the script uses only two of these - the total number of bytes of data transmitted and received by the interface.

      2. The folder '/sys/class/net/interface name/statistics/' contains files which accumulate network statistics for the interface. The script uses files 'rx_bytes' and 'tx_bytes' to obtain transmitted or received traffic.

      3.The well-known 'netstat -i' command is used to get network statistics for existing interfaces. Script uses 'RX-OK' and 'TX-OK' columns to obtains transmitted or received traffic.

How to identify your network interfaces

The following list displays commands generally available on devices running the TeamViewer IoT Agent.  Use any of the available commands to help identify your network interface details for use in integrating the BWM.

ifconfig -a

cat /proc/net/dev

ls /sys/class/net

netstat -i

ip link show

Testing the BWM

You can run the BWM manually to troubleshoot and/or see how it works.  To manually execute the BWM, run the following command, replacing "<existing network interface name>" with the network interface you want to monitor, e.g. eth0

/usr/local/teamviewer-iot-agent/monitoring/teamviewer_iot_bandwidth_monitor-1.0.0.sh -i <existing network interface name>

Upon successfully executing the BWM, the network statistics should be displayed in a JSON string, as shown in the example below:

{"InputTraffic":74352,"OutputTraffic":30349} 

The data represents the received/sent bytes between executions of the script.

Troubleshooting

The following error messages may be displayed if the BWM identifies an error.

Error

Description

Possible Resolutions

{"error":"Interface name is not defined"}

command line does not contain a network interface identifier or contains invalid syntax

provide an interface name to monitor (e.g. -i eth0)

{"error":"Not found interface - eth0"}

The specified interface name is not found

provide an interface name to monitor (e.g. -i eth0). 

See the section called How to identify your network interfaces for additional help

{"error":"User doesn't have permission to write file."}

the User does not have sufficient privileges to read, write, or execute into the folder containing the BWC

check folder & file permissions

{"error":"Cannot obtain network bandwidth."}

either the network monitoring methods do not exist or the BWM does not have sufficient permission to utilize the methods

ensure at least one of the methods described under the Notes section exist on the device and can be executed