Sonargraph Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID sonargraph-plugin Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.2
Jun 19, 2013
1.504
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Ingmar Kellner (id: ingmarkellner)
Esteban Angee (id: esteban-h2m)
Usage Installations 2013-May 67
2013-Jun 151
2013-Jul 225
2013-Aug 269
2013-Sep 313
2013-Oct 371
2013-Nov 424
2013-Dec 437
2014-Jan 493
2014-Feb 532
2014-Mar 590

Sonargraph Plugin

This plugin integrates Sonargraph into your build. Sonargraph allows to define an architecture for a software system and automatically checks how the code base conforms to it.

Contents

Introduction

Sonargraph analyzes the static (i.e. compile-time) dependencies of your software. The free-of-charge license for the integration with Jenkins and also Sonar allows to detect cyclic dependencies and additional metrics. You can mark the build as "unstable" or "failed" if cyclic dependencies are detected.
The real benefit of Sonargraph is that you can define a logical architecture and perform automatic checks how the code conforms to it. This functionality is only available for free, if you are working on a non-commercial Open-Source project or if your project is sufficiently small. More information is available on our homepage, you can check there if you are elligible for a free license.

The Sonargraph Build component integrates Sonargraph in Ant and Maven based builds. This Jenkins plugin allows to define if the build should be marked as "unstable" or "failed" if architecture violations, cyclic dependencies, etc. are detected. Trends of metrics are displayed in charts and additionally the generated detailed HTML report is available for each build.

Getting Started

If you already have Sonargraph integrated in your build, use the post-build step called "Sonargraph Report Analysis".

If you are new to Sonargraph, we advice you to register on our Sonargraph Web Site, have a look at the whitepapers and screencasts to get an idea of Sonargraph's capabilities.
You need to have a license in order to analyse a project. To get started an evaluation license or the free integration license is sufficient.
Download and install the correct version for your platform. A detailed user manual is available in <sonargraph-inst-dir/docs/pdf/Sonargraph-User-Manual.pdf that describes how to integrate the analysis into your build process.

If you are new to Sonargraph and your build is based on Maven, use the post-build step called "Sonargraph Report Generation & Analysis".

If you are new to Sonargraph and your build is not based on Maven, you need to install Sonargraph on your build server and generate the Sonargraph report during one of your build steps. This report can then be evaluated in the post-build step called "Sonargraph Report Analysis".

NOTE: This Jenkins plugin requires Sonargraph version 7.1.9 and newer.

Global Configuration

To see the global configuration options after installing the plugin, go to "Manage Jenkins" -> "Configure System". You will find the "Sonargraph Plugin" section

.

NOTE: This configuration is only required when you are going to use the "Sonargraph Report Generation & Analysis" post-build action.

Set the global options for Sonagraph as follows:

  • Sonargraph Product Type: Select either Sonargraph Architect or Sonargraph Quality according to the product that you have purchased.
  • Sonargraph Version: Select the version of the product from the combo box. Only versions equal or greater than 7.1.9 are supported by this plugin.
  • License File: Provide an absolute path to a Sonargraph valid license file in case you have one. License files are valid for up to 180 days.
  • Activation Code: Enter a valid Sonargraph activation code in case you have one. This operation requires Internet access as license tickets are renewed automatically.

You can use the hello2morrow web site, section "Your licenses" for managing license files and activation codes.

NOTE: If you haven't already used Sonargraph in your Maven build, you have to make sure that you specify the following plugin repository either in Maven's settings.xml, or in the project's pom.xml:

        <pluginRepository>
          <id>hello2morrow.maven.repository</id>
          <url>http://maven.hello2morrow.com/repository</url>
        </pluginRepository>

Sonargraph Report Analysis - Job Configuration

Use this post-build action for projects that are already using Sonargraph Build. This action analyses the generated report and allows to configure the overall result of the build depending on the results of the analysis. If you have a project that relies on ANT based builds this is the way to go to add Sonargraph functionality into your build job in Jenkins.

Make sure that you use the same values for the parameters "report directory" and "report name" that you have configured in your existing Sonargraph Build integration.
Additionally, add the flag "prepareForJenkins=true" to your existing Sonargraph build. (e.g. <createReportTask ... prepareForJenkins=true ... />).


 

Report Processing Configuration

The following parametern must be supplied to configure this post-build action:

  • Report Directory: Enter the path to the directory where the Sonargraph XML and HTML reports will be stored. This path must be relative to the workspace. If you are using the Sonargraph ANT task for report generation, make sure that the directories match.
  • Report Name: Enter the name of the XML report file that has been generated via the ANT or Maven integration of Sonargraph. If you are using the Sonargraph ANT task for report generation, make sure that the names match.

Basic options

For every Sonargraph metric supported by this plugin, you have the following options:

  • Don't mark: Will not change the build result in any way.
  • Build unstable: If the value for this metric is greater than zero, the build result will be set as "unstable".
  • Build failed: If the value for this metric is greater than zero, the build result will be set as "failure". 

Take into account that if you have set to mark the build unstable for one metric, failed for any other and both metric's value are greater than zero, the worst state will prevail, so the build will be marked as failure in this case.

Sonargraph Report Generation & Analysis - Job Configuration

Use this post-build action for integration of Sonargraph into Maven based projects that are not already configured to use Sonargraph Build. It will run Sonargraph's Maven goal generating XML and HTML reports for further analysis by this plugin.

After installing the Sonargraph plugin into Jenkins, go to the "Post-Build Actions" and select "Sonargraph Report Generation & Analysis". The following options will be displayed:   

Build Configuration

The following parameters must be supplied to configure this post-build action:

  • Maven Installation: Select the Maven installation that will run Sonargraph's goal. The elements displayed in this list will match the Maven installations configured in "Manage Jenkins" -> "Configure System".
  • Sonargraph System File: Enter the path to the Sonargraph system (.sonargraph) file. This path must be relative to the workspace. In case you have a Sonar / Jenkins license you must not provide a system file.
  • Report directory: Enter the path to the directory where the Sonargraph XML and HTML reports will be stored. This path must be relative to the workspace.
  • Use Sonargraph Workspace: Select if you want to use the workspace defined in Sonargraph. If unselected, the source and target folders defined in your pom.xml are used. This option must be unselected, if you don't provide a Sonargraph system file.
  • Prepare for Sonar: Select this option, if you want to publish Sonargraph metrics to Sonar.

Basic options

For every Sonargraph metric supported by this plugin, you have the following options:

  • Don't mark: Will not change the build result in any way.
  • Build unstable: If the value for this metric is greater than zero, the build result will be set as "unstable".
  • Build failed: If the value for this metric is greater than zero, the build result will be set as "failure". 

Take into account that if you have set to mark the build unstable for one metric, failed for any other and both metric's value are greater than zero, the worst state will prevail, so the build will be marked as failure in this case.

Known issue: In multi-module projects the goal "package" is executed again (skipping the tests) as in some cases sub-modules are reported as missing.

Sonargraph Job Page

For each job that the Sonargraph Jenkins Plugin is configured, a page is available that shows short-term trends of metrics for the last 25 builds and long-term trends of metrics for the complete job life-time.

To achieve reasonable performance for the creation of the charts, the number of sampling points for the long-term charts is limited to 300. If there are more sampling points available the data set is reduced by calculating averages for adjacent points. The displayed long-term trend is a 24h moving average.

Configure Logging

Sonargraph's Jenkins integration uses default Jekins mechanism to provide feedback to the user about the events that occur during the execution of the post-build actions or the generation of the graphics. To enable this feature follow these steps:

  1. Go to "Manage Jenkis" -> "System Log".
  2. Click "Add new log recorder" button.
  3. Provide the name you wish for this log recorder.
  4. In the field logger, provide the value with the exact value "com.hello2morrow.sonargraph.jenkinsplugin" (Without the quotation marks).
  5. Select the logging level for this logger.
  6. Click the save button.

You will now see an entry for the Sonargraph logger as shown in the image:

When first created this logger is going to be empty and you will be able to see messages as the post-build actions are executed and graphics are generated. Take into account that the messages will appear sorted by date in a descending order, meaning that most recent entries will be shown at the top.

FAQ

Will be elaborated in the future.

If your question is not answered here, please have a look at the Sonargraph_User_Manual.pdf contained in <sonargraph-inst-dir>/doc/pdf.
Further questions should be sent to:

Labels

Edit
plugin-external plugin-external Delete
plugin-post-build plugin-post-build Delete
plugin-sonargraph plugin-sonargraph Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.