= Jenkins RadarGun Plugin

Jenkins plugin for https://github.com/radargun/radargun/[RadarGun].

https://github.com/radargun/radargun/[RadarGun] is a data grid and distributed cache benchmarking framework built to test http://www.infinispan.org/[Infinispan] and other distributed data grid platforms. This plugin allows to run RadarGun benchmark as a Jenkins build step.

== Configuration === Global configuration First, you need to configure path to RadarGun distribution. Navigate to main Jenkins global configuration page, $JENKINS_URL/configure. Click Add RadarGun, specify name of the RG distribution and full path to the distribution. Distribution is expected to be unzipped in specified directory. Also, the directory has to be available on all RG nodes. Jenkins allows to install the tool automatically when it's missing on some machine. Unfortunately, this is not implemented yet, so please specify always installation directory.

=== Job configuration On job config page, click on Add build step and choose Run RadarGun. There are four fields, RadarGun instance, RadarGun scenario, Node list and Start script.

==== RadarGun instance Just choose one of the RG instances you configured on Jenkins global config page.

==== RadarGun scenario Specifies RG scenario to be run. You can specify either path to the scenario or provide scenario XML directly in job config page. Path to scenario as well as scenario itself can contain Jenkins and environment variables which get expanded before use.

==== Node list Probably the most complex part of the configuration, which specifies on which nodes RG main and workers should run and also allows to adjust parameters used in RG scenarios. It's in YAML format and can contain Jenkins and environment variables. Again, variables get expanded before use.

Config can contain arbitrary sections, which are valid YAML components. The only mandatory section is node list, which is a list starting with name nodes:. Each list item is one node, the first one is RG main, remaining ones RG workers. Each is represented by its hostname and optionally can contain map of other options. Following options can be used:

• [line-through]#jvmOpts#: plain string containing JVM options like -Xmx etc. This option is deprecated and will be removed in the future. As of RG 3.0, JVM options can be specified direcly in RG scenarios and this options is strogly preffered!
• javaProps: a map of java properties. Typically should be used for setting up parameters used in RG scenarios. Properties are entered without "-D" prefix, this will be added later on automatically.
• envVars: a map of environment variables and their values, which should be exported to given host.
• fqdn: main FQND or IP address, i.e. valid only for main node. If not specified, main hostname is used.
• beforeCmds: list of commands which will be executed before RG script on given node is started
• afterCmds: list of commands which will be executed after RG script on given node finishes
• gatherLogs: True/False determines whether logs should (not) be gathered from given machine. Default is True. Logs are sent to Jenkins main during the tests, so in case of excessive logging the bandwidth of the line can be reduced, which can impat the tests.

As mentioned above, only valid YAML elements are allows. With one exception - YAML allows to define some elements are referred it later on. However, it doesn't allow to include other files. This can be quite annoying as one wants to e.g. have default env. variable in one file and not copy it into each config. Therefore, plugin allows to use !include directive, which allows to include other files. File is inserted into the place where include directive is placed. As this is not a valid YAML directive, it should be used only when necessary a last resort!.

You can check https://github.com/jenkinsci/radargun-plugin/tree/main/src/test/resources[test resources folder], which contains examples of YAML config for tests.

==== Start script Specifies RG main and worker script to be used to starting and RG main and workers. This provides opportunity for the user to tweak command constructed by the plugin. It also allows to switch to other remote connection program, other than ssh. Usually it's sufficient to provide [source, shell]

!/bin/bash

set -x ssh $@

This option is deprecated and will be probably removed in the future.

=== Job results If RadarGun fails, i.e. RG main returns non-zero return code, Jenkins will fail the build. Once RG main or worker is started, Jenkins will create a link on the build page on upper-left side, which contains main or worker log. If the build is in progress, logs are update automatically. Besides logs, RG plugin doesn't do any archiving of build artifacts. If you want to archive RG results, you needs to add Archive the artifacts post-build action and configure pattern which artifacts should be archived, usually results/\**/*.

=== Running the plugin

• Maven 3.8 and Java 11
• mvn verify or mvn hpi:run

=== Running the test with IntelliJ In case you are using IntelliJ, please adjust the default setting in respect to whitespace fixes on save. The setting can be found in Settings -> Editor -> General -> On Save -> Remove trailing spaces on: Modified lines This will help minimize the diff, which makes reviewing PRs easier.

We also do not recommend * imports in the production code. Please disable them in Settings > Editor > Codestyle > Java by setting Class count to use import with '*' and Names count to use import with '*'_ to a high value, e.g. 100.

The addition of @{jenkins.addOpens} to argLine exposes a bug in IntelliJ IDEA. A patch has been proposed in JetBrains/intellij-community#1976. Pending the merge and release of this patch, IntelliJ IDEA users should work around the problem as follows:

1. Go to Settings > Build, Execution, Deployment > Build Tools > Maven > Running Tests.
2. Under "Pass to JUnit process [the] following maven-surefire-plugin and maven-failsafe-plugin settings", uncheck argLine.

Failure to work around the problem as described above will result in a could not open '{jenkins.addOpens}' failure when running tests in IntelliJ IDEA.