Visualize Network Performance in Jenkins with the MTR Plugin

As a system administrator or DevOps engineer, troubleshooting network latency and packet loss between servers is a critical but often tedious task. The jwms-mtr-plugin for Jenkins offers an elegant solution by integrating the powerful network diagnostic tool mtr (My TraceRoute) directly into your Jenkins environment, presenting the results as interactive visual graphs.

This plugin transforms raw command-line output into a clear, visual network map. Based on the project's GitHub page, here is a guide on how to set it up and use it in your Jenkins instance.

What is the jwms-mtr-plugin?

This Jenkins plugin allows server administrators to visualize network traceroute tool output directly within the Jenkins web interface. Instead of sifting through text logs, you get a dynamic graph that shows the network path between two hosts, making it easy to spot where latency or packet loss is occurring.

The project was created to provide a "repetitive success in network diagnostic collection, monitoring and report display," making it a valuable tool for automating network health checks as part of your CI/CD pipeline.

Key Features

• Interactive Visualizations: Uses the vis.js library to display network paths as an interactive graph.

• Geolocation Data: Can show the geographical location (country, region, city) of each hop when you point your mouse at a node.

• Flexible Node Configuration: Allows you to define multiple node pairs (e.g., host1->host2) to monitor network paths between various servers.

• Jenkins Integration: Seamlessly adds a "MTR Report" link to your Jenkins project's build page.

Step-by-Step Setup Guide

Here's how to get the plugin up and running in your Jenkins environment, based on the project's documentation.

1. Prerequisites

• Jenkins: A running Jenkins instance.

• Java: Java 8 or later.

• Python: Python 2 or later (for the helper scripts).

• MTR: The mtr command-line tool must be installed on all hosts you want to monitor.

• Jenkins Plugin: Download the .hpi file from the project's releases page.

2. Install the Plugin in Jenkins

1. In your Jenkins dashboard, go to Manage Jenkins > Manage Plugins.

2. Go to the Advanced tab.

3. Under the "Upload Plugin" section, choose the downloaded .hpi file and click Upload. Restart Jenkins if required.

3. Configure a Jenkins Freestyle Project

1. Create a new Freestyle project in Jenkins.

2. In the Build section of your project configuration, click Add build step and select 'Node Pair' from the dropdown list.

4. Configure SSH Credentials

In the build step configuration:

• Provide the SSH username, SSH password, and SSH port. The plugin will use these credentials to connect between the nodes you specify.

• The documentation recommends having a "common monitoring ssh user" for simplicity. Make sure this user has the necessary permissions to run mtr on the target machines.

5. Define Your Node Pairs

In the "Node pair" text area, define the pairs of hosts you want to trace. The format is simple: one pair per line, separated by ->.

host1.mydomain.com->host2.mydomain.com,

host2.mydomain.com->host1.mydomain.com,

host3.mydomain.com->host1.mydomain.com,

host1.mydomain.com->host3.mydomain.com,

6. Add Supporting Python Files

This step is crucial for the visualization and geolocation features.

1. Create a Directory: Create a directory on your Jenkins server that Jenkins can read (e.g., /var/lib/jenkins/mtr-data).

2. Copy Files: Copy the following files from the plugin's source repository (src/main/resources) into the directory you just created:

   • IP2Location.py

   • IPV6-COUNTRY-REGION-CITY-ISP.BIN (or an updated version)

   • sample.py

Note on Database Updates: You can download updated IP2Location LITE databases from their official site to get more accurate geolocation data. Just replace the .BIN file in your directory with the new one.

7. Run the Build and View the Report

1. Click Build Now on your project's main page. You can monitor the console output to check for any errors.

2. Once the build finishes, you will see a new 'MTR Report' link on the build's status page.

3. Click the link to view the interactive network graph.

8. Interact with the MTR Report

• The main visualization will show the network path between your defined nodes.

• Hover your mouse over a node (represented by PC icons or circles) to see detailed information, including the IP address, hostname, and its geographical country based on the IP2Location database.

Important Considerations

• Security: Be mindful of the SSH credentials you store in Jenkins. It is best practice to use a dedicated, limited-privilege user for monitoring tasks.

• File Permissions: Ensure the Jenkins process has read permissions for the directory where you placed the Python files and the IP2Location database.

• Maintenance: Remember to occasionally update the IP2Location database to keep geolocation data current.

Conclusion

The jwms-mtr-plugin is a fantastic example of a specialized Jenkins plugin that solves a specific operational problem with a beautiful user interface. By automating mtr runs and visualizing the results, it saves time and makes network diagnostic data accessible to the whole team. If you manage a distributed system, this plugin is definitely worth adding to your Jenkins toolkit.