Tutorial: Jenkins Plugin Development

Some time ago I thought about developing a plugin for Jenkins . Inspired by the Performance plugin, I wanted to develop a plugin for AppDynamics , making use of the REST interface it provides. It would enable to execute performance tests in e.g. an acceptance environment, and fetch certain performance measurements via the AD REST interface by supplying the start and end time of the test. My adventure however would be more of a challenge than I anticipated beforehand.

I started off trying to modify the Jenkins Performance plugin, this would be a troublesome exercise. The Performance plugin is based on reading files generated by JMeter. But because we can use a REST interface, less parsing and saving of files is necessary.

Marcel Birkner already did a great post about a Jenkins plugin for Nexus , which I’m not going to repeat. The Jenkins Wiki is also a good starting point. There are also some other tutorials you can find on the Internet, I found them somewhat limited however, so I’ll try to go more in-depth and hopefully add another valueable tutorial.

The sources can be found on GitHub: AppDynamics Jenkins Plugin

Project Setup

The following will be a summary, for more detail see Marcel’s tutorial .

First create the Maven project:

1$ mvn -cpu hpi:create

To easily test the plugin, I wrote the following bash script (in case you’re using Linux or Mac), named run-fast.sh:

1#! /bin/sh
2rm -rf work/plugins
3mvn -Dmaven.test.skip=true -DskipTests=true clean hpi:run

I wanted to easily reload the plugin while developing, without restarting Jenkins every time. Unfortunately I haven’t found a way that the Jetty container / Jenkins will correctly reload the updated class files for the plugin. If you find a way (other than JRebel), please let me know. In the mean time, after code changes are made, exit the Jenkins run script (^c) and restart the script again.

Necessary Plugin Objects

For your plugin to hook into the Jenkins build system, certain classes need to be extended so that they are discovered automatically. I will first give an overview of the main classes our plugin is using and will later describe them in more detail.

• AppDynamicsResultsPublisher  – extends –  Recorder
  The Recorder is a specific BuildStep intended to run after the build completed, collects statistics from the build and marks it as unstable / failed.
• AppDynamicsBuildAction  – implements –  Action and StaplerProxy
  Actions are exposed and create an additional URL subspace. They can appear e.g. in the left-hand menu of a build and these objects are persisted to disk. By adding the StaplerProxy interface we can point to a different ModelObject which is our BuildActionResultsDisplay.
• BuildActionResultsDisplay  – implements –  ModelObject
  A ModelObject is some object referenced by an URL. It can be referenced e.g. by Jelly pages which we’ll describe later.
• AppDynamicsProjectAction  – implements –  Action
  Another Action but this time on project level instead of individual build level.

To expose the above objects on the Jenkins web interface, corresponding Jelly files are necessary. There are various types and to map them to certain classes (for retrieving the actual data or graphs) the paths need to match. For example to display the outcome of a specific build, we have a Jelly file on the following path:

/nl/codecentric/jenkins/appd/BuildActionResultsDisplay/index.jelly

This file maps to the BuildActionResultsDisplay class (remember, proxied by AppDynamicsBuildAction) and can show its data.
Other types of Jelly files are (which can live besides each other in the same directory):

• config.jelly – for configuration, mainly on Publisher (our Recorder) level to configure the plugin
• floatingBox.jelly – can show a floating graph on a build or project page
• summary.jelly – can show a summary on a build or project page

Now let’s go into more detail…

Publisher

The Publisher object or Recorder is the base of our plugin. It needs a BuildStepDescriptor to provide certain information to Jenkins, but this descriptor also makes it possible to provide defaults for certain configuration fields and even to validate data. Below is a snippet of the descriptor.

1public static class DescriptorImpl extends BuildStepDescriptor {
2 
3    @Override
4    public String getDisplayName() {
5      return PUBLISHER_DISPLAYNAME.toString();
6    }
7 
8    public String getDefaultUsername() {
9      return DEFAULT_USERNAME;
10    }
11 
12    public ListBoxModel doFillThresholdMetricItems() {
13      ListBoxModel model = new ListBoxModel();
14 
15      for (String value : AppDynamicsDataCollector.getAvailableMetricPaths()) {
16        model.add(value);
17      }
18 
19      return model;
20    }
21 
22    public FormValidation doTestAppDynamicsConnection(@QueryParameter("appdynamicsRestUri") final String appdynamicsRestUri,
23                                                      @QueryParameter("username") final String username,
24                                                      @QueryParameter("password") final String password,
25                                                      @QueryParameter("applicationName") final String applicationName) {
26      FormValidation validationResult;
27      RestConnection connection = new RestConnection(appdynamicsRestUri, username, password, applicationName);
28 
29      if (connection.validateConnection()) {
30        validationResult = FormValidation.ok("Connection successful");
31      } else {
32        validationResult = FormValidation.warning("Connection with AppDynamics RESTful interface could not be established");
33      }
34 
35      return validationResult;
36    }

The methods that return a FormValidation object provide a nice way of validating input, or in this case verifying that the connection to the AppDynamics REST interface is valid. It is coupled to our Jelly file in the following way (snippet from config.jelly):

1<f:entry title="${%appdynamics.rest.username.title}" description="${%appdynamics.rest.username.description}">
2    <f:textbox field="username" default="${descriptor.defaultUsername}" />
3  </f:entry>
4 
5  <f:validateButton
6      title="${%appdynamics.connection.test.title}" progress="${%appdynamics.connection.test.progress}"
7      method="testAppDynamicsConnection" with="appdynamicsRestUri,username,password,applicationName" />

The “validateButton” gives a separate button that will invoke the doTestAppDynamicsConnection method of our AppDynamicsResultsPublisher class. For validation of fields, it is sufficient to add a doCheckxxx method where xxx maps to the correct parameter name and where you add an @QueryParam annotation to the method input parameter.The descriptor needs to be bound to the corresponding class as follows:

1@Extension
2  public static final DescriptorImpl DESCRIPTOR = new DescriptorImpl();
3 
4  @Override
5  public BuildStepDescriptor<Publisher> getDescriptor() {
6    return DESCRIPTOR;
7  }

Finally, the perform method will be executed whenever a build is started. From here, also the AppDynamicsBuildAction must be instantiated, shown in the following snippet:

1@Override
2  public boolean perform(AbstractBuild<?, ?> build, Launcher launcher, BuildListener listener)
3      throws InterruptedException, IOException {
4    PrintStream logger = listener.getLogger();
5 
6    AppDynamicsDataCollector dataCollector = new AppDynamicsDataCollector(connection, build,
7        minimumMeasureTimeInMinutes);
8    AppDynamicsReport report = dataCollector.createReportFromMeasurements();
9 
10    AppDynamicsBuildAction buildAction = new AppDynamicsBuildAction(build, report);
11    build.addAction(buildAction);
12 
13    ...
14 
15    Result result;
16    if (performanceFailedThreshold >= 0
17        && performanceAsPercentageOfAverage - performanceFailedThreshold < 0) {
18       build.setResult(Result.FAILURE);
19     } else if (performanceUnstableThreshold >= 0
20        && performanceAsPercentageOfAverage - performanceUnstableThreshold < 0) {
21      result = Result.UNSTABLE;
22      if (result.isWorseThan(build.getResult())) {
23        build.setResult(result);
24      }
25    }

Everything written to the logger will show up in the build console output.

Build Action

The most important thing to know about the AppDynamicsBuildAction is to provide a weak reference to our BuildActionResultsDisplay object and return it as target so it can be shown on the build page:

1private transient WeakReference buildActionResultsDisplay;
2 
3  public BuildActionResultsDisplay getTarget() {
4    return getBuildActionResultsDisplay();
5  }
6 
7  public BuildActionResultsDisplay getBuildActionResultsDisplay() {
8    BuildActionResultsDisplay buildDisplay = null;
9    WeakReference wr = this.buildActionResultsDisplay;
10    if (wr != null) {
11      buildDisplay = wr.get();
12      if (buildDisplay != null)
13        return buildDisplay;
14    }
15 
16    try {
17      buildDisplay = new BuildActionResultsDisplay(this, StreamTaskListener.fromStdout());
18    } catch (IOException e) {
19      logger.log(Level.SEVERE, "Error creating new BuildActionResultsDisplay()", e);
20    }
21    this.buildActionResultsDisplay = new WeakReference(buildDisplay);
22    return buildDisplay;
23  }
24 
25  public void setBuildActionResultsDisplay(WeakReference buildActionResultsDisplay) {
26    this.buildActionResultsDisplay = buildActionResultsDisplay;
27  }

Our BuildActionResultsDisplay will actually expose the data for a certain build. It is fed with a AppDynamics report containing all information for / from the build. The class will parse the data and generate e.g. a graph as shown in the code and corresponding Jelly:

1public void doSummarizerGraph(final StaplerRequest request,
2                                final StaplerResponse response) throws IOException {
3    final String metricKey = request.getParameter("metricDataKey");
4    final MetricData metricData = this.currentReport.getMetricByKey(metricKey);
5 
6    final Graph graph = new GraphImpl(metricKey, metricData.getFrequency()) {
7    ....
8    };
9 
10    graph.doPng(request, response);
11  }

1<j:set var="report" value="${it.getAppDynamicsReport()}"/>
2      <j:forEach var="metricData" items="${report.metricsList}">
3              
4      </j:forEach>

Project Action

Finally the AppDynamicsProjectAction is quite similar to the previous objects. One thing that is interesting though is how to get a list of all previous reports, as we would like to show some overall statistics. The following code shows how the AbstractProject can be used to fetch a list of builds and from each build grab the stored AppDynamicsReport object:

1private List getExistingReportsList() {
2    final List adReportList = new ArrayList();
3 
4    if (null == this.project) {
5      return adReportList;
6    }
7 
8    final List<? extends AbstractBuild<?, ?>> builds = project.getBuilds();
9    for (AbstractBuild<?, ?> currentBuild : builds) {
10      final AppDynamicsBuildAction performanceBuildAction = currentBuild.getAction(AppDynamicsBuildAction.class);
11      if (performanceBuildAction == null) {
12        continue;
13      }
14      final AppDynamicsReport report = performanceBuildAction.getBuildActionResultsDisplay().getAppDynamicsReport();
15      if (report == null) {
16        continue;
17      }
18 
19      adReportList.add(report);
20    }
21 
22    return adReportList;
23  }

Conclusion

What seemed like a quite daunting task eventually (after lots of struggeling) turned out to be quite easy. I hope by writing this blog post that some ideas and principles behind Jenkins become a bit more clear. And without adding too much other stuff, you have gotten a nice overview of which basic classes are necessary for a Jenkins plugin.

Now go and write your own plugin!!