JMeter (Jenkins + GitHub)
Table of Contents
Advanced - This article is part of a series.
What is Jenkins? #
Jenkins is a continuous integration tool based on the open source project Hudson, which was started in 2004 by Sun Microsystems. However, as we all know, Sun Microsystems was acquired by Oracle Corporation in 2010, so the rights to Hudson were claimed by Oracle, and on January 2011, it was decided to change the name to Jenkins, although both projects continue until this day. There are many similarities between these two tools, but the community of Jenkins is much larger. Some alternative continuous integration tools include:
How does Jenkins work? #
Basically with Jenkins you can create flows or pipelines with multiple stages. This means that actions (jobs) can be automated, which could be connected by stages and subject to specific conditions, such as whether the action is successful or not. For example, if an action has a code exit status of zero, it would indicate that it ended correctly; otherwise, if the code exit status were different from zero, it might indicate a compilation, construction, or execution failure in the action. Therefore, you could stop or halt the entire pipeline or flow.
Remember that there are many plugins that can be installed in Jenkins to integrate various communication channels for alerting people involved when the pipe or flow is blocked for some reason. Depending on the process and management of it, it will either start over from the beginning or continue with errors, which is possible if there is tolerance for failures.
What is Github ? #
GitHub is a distributed and collaborative platform for version control of type Git, specifically directed at managing and administering source code. GitHub is based on the framework Ruby on Rails and written in the programming language Ruby. In 2018, GitHub was acquired by Microsoft and with it several companies that had their source code hosted on GitHub migrated to similar tools like:
Something worth mentioning about GitHub that contributed greatly to its popularity was the fact that it supported one of the largest DDoS (denial of service distributed) attacks in history. On February 28, 2018, it handled up to 1.35 Tbps (terabits per second) sent through 126.9 million packets per second via a vector attack from apparently 100,000 Memcached servers, and this was successfully contained thanks to the Akamai Prolexic service. There are strong suspicions that the main reason for the attack was to steal the source code of large software companies.
How does GitHub work? #
GitHub primarily functions through repositories, each repository having its own webpage on the platform as well as a Wiki. Once the repository is created, files are uploaded to it using the commands git add, git commit, and git push. You can consult all of Git’s basic orders here: Git Basic Orders. This is for code versioning. The tool also has other features such as a graphical interface (GUI) available on Linux, MacOS, and Windows platforms, the GitHub.com platform, Wiki, Kanban, and social interaction types, among others. What we are interested in for this publication is to create a public repository for our integration.
How does the integration of Jenkins and GitHub with JMeter work? #
The integration is simple; you just need to create a public repository on GitHub where we have our JMeter script hosted, so that Jenkins can clone this local repository and have the desired version of the script for starting the execution. The execution will be carried out via the distributed master-slave scheme, which can be over a private (local) or public network. The results will be saved in Jenkins’ workspace area to be consulted later and also published as HTML through an Apache Web server.
- Update our JMeter (JMX) script on GitHub.
- The Jenkins project requests the local cloning of this repository.
- GitHub allows for the cloning of repositories (also can be a private repository).
- Jenkins runs locally the JMeter (controller) in distributed mode on the node.
- The node sends results via RMI to the server controller (Jenkins), and these results are stored in the workspace.
- Results are published in the Apache server’s directory and shared in HTML format.
Why Use GitHub in Integration? #
The main reason for recommending the use of a version control platform is to avoid updating the JMeter (JMX) script directly on the Jenkins server or load generator. This can lead to errors, such as manually placing an incorrect file or version. Remember that fewer access points mean better confidence in the results.
Remember that the repository used can also be private, but for this to happen you will need to configure access credentials for the repository.
Why Use a Distributed JMeter Script? #
I strongly advise against running the test from the same server where Jenkins is hosted. This is a very popular bad practice, and I don’t need to list all the reasons why it’s a bad practice; but if there are any doubts about this publication, please consult it.
Can I use alternatives to Jenkins or GitHub? #
Yes, the publication covers the configuration and overall idea, so you can replace Jenkins with any other continuous integration tool, or also switch GitHub with any other version control system.
What do we need? #
We need a Apache web server installed that basically just runs a couple of commands; it also needs to have Jenkins installed and configured so we can manually install the Git integration. We also need a Git repository where our JMeter script will be hosted, if it’s public then no additional installation is necessary; in case of a private repository, you’ll have to install GitHub authentication plugin. Finally, install and configure JMeter in distributed mode on Jenkins (controller) and the node (load generator) using the guidelines mentioned earlier.
Recipe for cooking #
1.- Create a Project #
Let’s create an open-source project, and there we will configure the GitHub repository. For this example, I used the repository JMeter_Script.
2.- Configure the project #
We will also configure four parameters that will adjust the number of concurrent users, ramp-up time, and test duration. Finally, we will introduce the remote server IP address where the tests will be executed. To perform this task, you need to follow the following publications depending on whether you are in a private or local network or public network. Also, the script should be prepared to accept parameters as shown in this publication.
Command line for running JMeter, as the report is automatically generated at the end of the test in the Workspace. For this test, JMeter was downloaded and installed into the Jenkins controller within the JENKINS_HOME directory to avoid permission issues.
Command for Jenkins Linux/Unix/MacOS
$JENKINS_HOME/JMeter/apache-jmeter-5.3/bin/jmeter.sh -n -t $WORKSPACE/JMeter_Script_Plugins.jmx -l $WORKSPACE/JMeter_Script_Plugins-$BUILD_NUMBER.jtl -Jthreads=$Threads -Jrampup=$RampUp -Jduration=$Duration -R $RemoteEngine -e -o $WORKSPACE/$BUILD_NUMBER
Command for Jenkins Windows
%JENKINS_HOME%/JMeter/apache-jmeter-5.3/bin/jmeter.bat -n -t %WORKSPACE%/JMeter_Script_Plugins.jmx -l %WORKSPACE%/JMeter_Script_Plugins-%BUILD_NUMBER%.jtl -Jthreads=%Threads% -Jrampup=%RampUp% -Jduration=%Duration% -R %RemoteEngine% -e -o %WORKSPACE%/%BUILD_NUMBER%
Command to copy results from the Workspace to the Apache server, so they are available for all users from any location. It should be noted that a reports folder must be created and permissions granted to the Jenkins user to write in it.
cp -R $WORKSPACE/$BUILD_NUMBER /var/www/html/reports/
3.- Execute the project #
Execution of the test, for this purpose we will select the option “Build with Parameters” (Construir con parámetros), these parameters will be pre-filled with the values defined by us. Once in execution, we will enter the results of the build id (in this case #2) and review the output of the “Console Output”. After completing the test, we verify that the results are stored in the workspace.
The most recommended is to generate an image of the server node so that it can be stopped when not running the test (to save costs) and when needed, we can start it and obtain the new IP address of the server node to update the parameter value before each execution.
4.- Review results #
Finalize by reviewing the report through a web browser:
Conclusion #
This solution appears to be the best way to reliably execute your load testing and obtain results that you can share or visualize outside of Jenkins, since if you need to review specific graphs or results, you don’t have to enter Jenkins to get them. It would also be quite simple to obtain the result tables as we could observe in the last web image, so comparing and exporting result tables would be extremely useful. If we had multiple applications, we could create multiple directories like /reportes/app1/ /reportes/app2/ etc., and easily access hundreds of results from a browser.
We must ensure that the JTL result files from the workspace (Workspace) are safeguarded and backed up. This is very important because if the Jenkins server fails, it’s crucial to have backups of these valuable historical results. It should be noted that this opportunity lies in security and exposure of such results. It is not advisable always to work with administrators managing Jenkins, Git or Web services to reinforce security and permissions before exposing sensitive internal or external information.