Writing Your Own SonarQube Plug-ins – Part 2: Defining Custom Metrics and Sensors

In part 1 of this series here, I explained the basics of SonarQube plug-ins and how to start writing your own plug-in.

A plug-in may consist on a series of Metrics, Sensors, Decorators and Widgets, although not all of them are required in any single plug-in.

Metric classes define custom metrics, Sensors are used to scan projects and calculate metric values (measures, in SonarQube terminology), Decorators are used to calculate derived values for a given project resource (typically using several measures to do the calculation) and Widgets are used to present information in SonarQube dashboard.

When designing a new SonarQube plug-in, it’s important to differentiate between Sensors and Decorators. A Sensor is executed once per analysis. It typically scans the project folder structure recursively, calculating metric values, i.e. with the help of an external tool, and stores the information in SonarQube database. A Decorator is executed once per resource, after all Sensors are executed. Decorators can query for existing metric values, calculate derived values and store them in SonarQube database. Decorators are typically used to calculate aggregated values or to calculate metrics that rely on values coming from multiple sources.

Part 2 – Defining Custom Metrics and Sensors

The plug-in we are developing during these posts is a simple one that collects information from IDE configuration files, i.e. whether the project is configured as a Web project, an EJB project, etc.

The plug-in will rely on a EclipseAnalyzer class to do the hard work (details not interesting for the purpose of these posts).

A Metric class will define the set of metrics that this plug-in will gather. A Sensor class will execute the EclipseAnalyzer on the context of the analysis, and store the results using SonarQube API (no direct database access is allowed, an it’s much simpler this way).

Let’s view a bit more in detail of each one.

Defining a Metric Class

A Metric class in SonarQube API is very simple to define: create a class implementing the interface org.sonar.api.measures.Metrics. This interface only specifies one method to be implemented: List<org.sonar.api.Metric> getMetrics(). That is, a simple method returning a list of Metric objects.

Each Metric object returned will represent a Metric entity in SonarQube model. Each Metric can store value of a certain data type (boolean, string, integer values, floating-point values, percentages, etc.), be qualitative or quantitative, aggregated automatically in some direction (upward or downward), and other characteristics.

The simplest way to define a Metric is to use the Metric builder pattern, as can be seen in code fragment below:

public static final Metric IDE_IS_JAVA =
    new Metric.Builder(
        "ide_is_java", // metric identifier
        "Java project", // metric name
        Metric.ValueType.BOOL) // metric data type
    .setDescription("Whether the project is configured as Java in the IDE")
    .setQualitative(false)
    .setDomain(CoreMetrics.DOMAIN_GENERAL)
    .create();

After defining as many metrics as needed, the implementation of the getMetrics() method is straightforward:

public List<Metric> getMetrics() {
    return Arrays.asList(
        IDE_PRJ_NAME, IDE_IS_JAVA, IDE_IS_EAR, IDE_IS_EJB, IDE_IS_WEB,
        IDE_IS_GWT, IDE_IS_GAE, IDE_IS_GROOVY, IDE_IS_GRAILS,
        IDE_IS_PDE, IDE_IS_JET, IDE_DEPENDENCIES, IDE_CLASSPATH);
}

Defining a Sensor Class

A Sensor class in SonarQube API is also very simple to define: create a class implementing the interface org.sonar.api.batch.Sensor and implement the two specified methods.

The first one is boolean shouldExecuteOnProject(org.sonar.api.resources.Project), that tells SonarQube analyser whether it should execute on any particular project or not. The Project object provides the information needed to take decision: the project name, language, analysis type, the list of modules it contains, etc. In our case, it will always return true.

The second one is void analyse(org.sonar.api.resources.Project, org.sonar.api.batch.SensorContext). This is the method where all the magic happens: inside it the project resources will be scanned, metric values calculated and stored in SonarQube database – hopefully with the help of other classes and methods.

To get access to the project directory structure, the recommended way is to leverage the dependency injection mechanism of the Plexus container where SonarQube analysis runs. Let’s define a constructor this way and Plexus will do the rest for us:

public IDEMetadataSensor(org.sonar.api.scan.filesystem.ModuleFileSystem fileSystem) {
    this.fileSystem = fileSystem;
}

Independently of the mechanism used to calculate metric values, once they are ready, they will be store using the saveMeasure(org.sonar.api.measures.Measure) method of interface org.sonar.api.batch.SensorContext.

A Measure is created using a simple constructor with metric id and value. The sensor context will determine the resource to which the metric value belongs to.

For example:

Measure measure = new Measure(IDEMetadataMetrics.IDE_PRJ_NAME, projectInfo.getProjectName());
sensorContext.saveMeasure(measure);
measure = new Measure(IDEMetadataMetrics.IDE_IS_JAVA, projectInfo.isJavaProject() ? 1d : 0d); // for boolean values, 1 is true, 0 is false
sensorContext.saveMeasure(measure);

When a measure (or a violation if our plug-in is profiling code) needs to apply to a specific resource inside the project, i.e. a Java class, you can use the sensorContext.getResource() method to obtain the right place and use it to create and save the measure using the saveMeasure(Resource, Measure) method.

Finally, when in doubt, it’s always useful to access SonarQube plug-in source files on GitHub, and take a look to Checkstyle or FindBugs plug-ins.

What’s next

Next, in part 3, I will explain how to create widgets and finally in part 4 I will explain how to execute the plug-in in development mode and how to install it in your production SonarQube instance, with the help of JRebel to speed up development.

About these ads

9 thoughts on “Writing Your Own SonarQube Plug-ins – Part 2: Defining Custom Metrics and Sensors”

  1. Hi,
    Great job, nice tutorial.

    I’m working in developing a plugin! I’d be very grateful if you could send me a bit more information about this topic.

    My main objective is coding my new own rules but I’m a bit lost right now.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s