Sonar workspace

The Sonar web site is divided into 3 main areas:

• "All Projects" area
• Project area
• Configuration area

When logged in to Sonar, it is possible to access some more areas that are not going to be described here.

The top bar

Whatever the area you are in, there is top bar :


This bar allows, from left to right, to :

• go back to the Home / All projects page
• search for a project in free text
• display a breadcrumb trail to keep track of the current location (clickable)
• Browsing quality profiles
• Log into Sonar as an admin
• print the current page
• a permalink to the page

The left menu

The left menu is a contextual menu that depends of the area you are in Sonar. Since v1.5, it is possible to add entries into this menu by Writing a Sonar plugin

In the All Projects page

In the project area

There are several entries there that enable to get more information on the project. Those entries are described in the Browsing a Project section.

In the configuration

When clicking on the configuration link at the top right of the pages, you are presented with the following menu:

Print Sonar page

When printing a Sonar page, the left and top navigation bars are automatically removed.
By default, Treemaps are not correctly printed by browsers and you need to specify your browser to print background colors to fix this issue.

In Firefox :

In Internet Explorer :

Browsing All Projects

When launching Sonar web site, the Home page gives a consolidated view enabling to browse all projects.


This page is divided into 2 : the list of projects and the treemap. In order to browse a specific project, click on the name of the project, either from the project list or from the Treemap.

The list of projects

The list of projects is a table in which appear all the projects already sonarized. Along with each project come information about the latest analysis of the project as well as indication about evolution throughout time.



For example in the above screenshot, number of lines of code, code coverage... When several analysis have been made on a project,  little arrows will appear next to measures : those are called Tendencies and give some indication on the evolution of the measure.

Where there is a left hand side icon, it means that there are alerts defined in the quality profile used to analyze the project. The various icons indicated if alerts are triggered or not. A RSS feed enables to subscribe to status change of alerts using the link at the bottom left of the page.

Any measure that has reach a threshold defined in an alert will be highlighted in orange for a warning, in red for an error.

It is possible to sort by column by clicking on the header of the column.

This page can be configured. See Personalize "All projects" for more details.

The treemap

The treemap is a bi-dimensional representation of the projects data. This is a square in which each project is represented by a sub-square.

The size of the sub-square represents generally a quantitative measure on the project like the number of lines of code or the total cyclomatic complexity. The color of the sub-square represents a qualitative measure like the cyclomatic complexity per method, the Rules Compliance Index... The default values for both those dimensions are configurable. See Personalize "All projects" for more details.

When passing the mouse over on a project, the information represented will be displayed.




The treemap being a view to compare information between projects, it will appear only when 2 or more projects have been analyzed.

It is possible to hide the treemap in the Home page. See Personalize "All projects" for more details.

Browsing a Project

Zooming on a specific project leads to the dashboard of the project page.

The Dashboard

This is the entry point on each projects. It gives a synthetic view on the project. The dashboard is divided in widgets.

1. General information

Two widgets display standard metrics

Next to each measure, will appear a tendency for the measure.

When a measure appears in color, it means than a warning (orange) or error (red) threshold has been reached. Passing the mouse over the measure will give some more information on the alert.

Clicking a on any measure opens the Measures Drilldown, zooming on the measure chosen.

2. The Rules Compliance Index (RCI)

The RCI is a second-level metric calculated by Sonar. It gives a ratio between weighted violations and the number of lines of code.



Next to the RCI, a radar shows how iso categories are respected. Clicking on one of the categories opens the Violations Drilldown, zooming on the chosen category.
To understand how the RCI is calculated, check the Rules Compliance Index section.

3. The project Treemap

The Project Treemap is very similar to the "All Projects" Treemap. It simply displays information at the project level. The Treemap is a generic component that adapts depending on the structure of the project: modules, packages and classes.

The Treemap will show the components that are at level 1, regardless of the type. The Treemap allows to drill down into any component to get a view on the component.

4. The manual measures

The manual measures have been added to Sonar in order to be able add some information from other systems into Sonar. It is possible to add information at any level in the project, module, package. Those measures are called Manual Measures because they are entered manually into Sonar.

Those manual measures will behave the same way as the other : you get historical data, you can see trends...

To enter manual measures or create categories of manual measures, see the Manage measures.

5. The Events

The Events section is used to highlight events occurring during the lifetime of the project. There are two families of events :

• manual : it is possible to add manual events and to create categories of events. See the Manage events for more details
• automated : a mechanism exists in Sonar to pick automatically events and record them. This is the case for version events (picked when the version changes in the pom.xml) and for alert events that are triggered when a threshold has been reached.

Measures Drilldown

Wherever in a project, it is always possible to access the Measures Drilldown by clicking on a measure.



You then see the component structure : hierarchy is represented from left (higher) to right (lower). At the top of each list appears the component that has the most the "measure that was selected".

By clicking on a class, this will show the source code of the class. See The resource viewer for more details. 

Violations Drilldown

Wherever in a project, it is always possible to access the Violations Drilldown through the left menu.



The top section is used to select the scope of violation : priority, category, specific rule.

The bottom section represents hierarchy from left (higher) to right (lower). At the top of each list appears the component that violates the most the scope selected.

By clicking on a class, this will show the source code of the class. See The resource viewer for more details.

Coverage Clouds

Wherever in a project, it is always possible to access the Coverage Clouds through the left menu. This brings to a page where it is possible to choose one of two tabs :

• The top risk tab : the size represents the average complexy by method in the class. The color represents the code coverage or the Rules Compliance Index (drop down on the top right)
• The quick wins tab : the size represents the lines of code in the class. The color represents the code coverage or the Rules Compliance Index (drop down on the top right)

By clicking on a class, a third tab will open, showing the source code of the class. See The resource viewer for more details.

Hotspots

Wherever in a project, it is always possible to access the Hotspots through the left menu. This brings to a page where several widgets appear, each of them showing the top 5 of most... or top 5 of less... This is a way to get a picture of where to start from in a project.

Components

Wherever in a project, it is always possible to access the Components through the left menu. This brings to a page similar to the home page, where lines represent the components of level n-1

The resource viewer

The resource viewer is a tool that enables to view source code and unit tests. The power of the tool comes from the fact that the resources can be viewed with different axis of quality. On each of the axis a permalink is provided to allow to jump from an external tool or document directly into a resource.

Viewing source code

When drilling down into measures, you will eventually reach the class level and will be able to browse the source code.

At the top, 4 tabs representing 4 different views on the code source.

In the middle, a contextualized header depending on the selected tab

At the bottom, the code source contextualized, depending on the chosen tab.

The Sources tab

This tab shows the plain source code as is.

The Code coverage tab

The code coverage tab shows the source code annotated with extra information and colors showing the code coverage.



In the second column, next to each line of code (except empty lines and comments) appear the number of times the unit tests have "hit" the line. If it is 0, the line will be highlighted in red, otherwise the number of hit appears in green.

The Violations tab

The violations tab shows the source code annotated with extra informations and colors showing the coding rules violations. By default, only the code immediately next to the violation is shown.



A drop down list enables to filter on a specific violation or on a specific priority.

The Duplications tab

The duplications tab shows every duplicated chunk of code within a class and the name of the other class it is duplicated with.

Viewing the unit tests results

When drilling down into unit tests measures (except the code coverage), you will eventually reach the unit test class level.

At the top, 2 tabs representing 2 different views on the unit tests classes.

In the middle, a contextualized header depending on the selected tab

At the bottom, the code source contextualized, depending on the chosen tab.

The Sources tab

This tab shows the plain source code of unit tests classes, as is.

The Tests tab

This tab shows the result of the unit tests belonging to the unit test class. In case the test failed or was in error, the reason for the error can be viewed.

Browsing quality profiles

By going to the configuration menu at the top right, it is possible to view the quality profiles defined in Sonar.



For each profile, there is information :

• Name of the profile
• Number of mandatory rules activated ( + number of optional rules)
• Possibility to export Checkstyle and PMD rule definition for the profile
• Number of alerts defined within the profile
• The default profile to be used for analysis
• Number of projects specifically associated to the profile

And there is specific information, divided in three section:

Coding rules configuration

To browse the coding rules configuration for the profile, click on the name of the profile or on the number of rules activated.



At the top, a powerful search engine enables to filter easily the rules you are interested in, using the name of the rule, the plugin, the priority or the category it belongs to and whether it is activated or not.

At the bottom of the page, the list of rules that was filtered out. For each rule, the level of activation, the name, the plugin and the family. By clicking on the name, you expand the rule and get a description of the rule as well as its parameters if any.

Alerts configuration

To browse the alerts configuration for the profile, click on the number of alerts defined for the profile.



The list of alerts shows up : each alert consists of a metric, an operator and two thresholds, one for warning and one for error.

Association between projects and alerts

To see which projects are associated explicitly to a profile, click on the number of projects defined for the profile.



The list of alerts shows up : each alert consists of a metric, an operator and two thresholds, one for warning and one for error.

Exploring the TimeMachine

Wherever in a project, it is always possible to access the Time Machine functionality through the left menu.



The Time machine enables to reply the past by looking at a series of past analysis. The Time machine page is divided into 4 sections.

The custom chart

This chart represent a timeline from the first ever analysis to the last ever analysis. On this timeline will appear all the metrics that are ticked below

To change the metrics appearing on the chart, tick the metrics you are interested in and press at the bottom of the page. The chart is then regenerated with the chosen metrics.

Every event, either generated or manually entered appear on the chart as vertical doted lines.

It possible to change the default metric appearing on the chart. View the Manage Time Machine section for more details

The chosen analysis

When launching the Time Machine, Sonar displays the first snapshot ever and the last 5 events in the system.

It is possible to add snapshots to the view : snapshots can be selected either by date


or by events (only version events will be listed)


It is possible to hide a snapshot from the view by using the hide link next to the snapshot to be removed

The chosen columns do not currently have any influence on the custom chart

The metric table

On the left of this table will appear the list of all possible metrics (grouped by families) stored in the system, including the manual metrics. Each column represents a snapshot and will display the measure for the metric. At the right of the table appears a sparkline showing the evolution of the chosen snapshots.

The complexity chart

This chart compares the repartition of the classes complexity between all the chosen snapshots.

Rules Compliance Index

The Rules Compliance Index (RCI) is an advanced metric calculated by Sonar.

During data collection, Sonar collects data from 3 rule engines : checkstyle, PMD and FindBugs. Sonar then aggregates, based on the configuration of each of the rule, the number of times rules have been violated in the project.

That is how Sonar compiles the RCI = 100 - ( weighted_violations / nloc * 100 )

More detail on metrics is available here.

Tendencies

What are Tendencies ?

The tendencies are visible in every screen, from portfolio to class view, and are materialized by little arrows next to each measure. Those arrows show the trend for the measure.
This page intends to explain how to read them, how Sonar makes their calculation and how they can be used.

How to read Tendencies ?

Sonar uses 5 levels to describe the tendency of a measure. Each level is represented by an arrow :

	Strong increase
	Medium increase
	Neutral
	Medium decrease
	Strong decrease

Sonar uses black ( ) arrows to represent tendencies on the quantitative metrics (the ones that are not reflecting quality of the code, for example number of lines of code).

Sonar uses red ( ) or green ( ) arrows to represent tendencies on the qualitative metrics (the ones that are reflecting quality of the code, for example code coverage). The red is used when the quality decreases, the green when it increases.

Of course, it is to be noted that if the percentage of duplicated lines decreases it will be represented by because it is considered as an improvement.

How are Tendencies calculated ?

In order to display the tendencies, making a simple difference between the last two measures of each metric would not be accurate enough. Therefore Sonar implements a more advanced algorithm : the least squares method. The least squares is a linear regression analysis that helps removing the noise in order to determine a trend on discrete measures.
In other words, Sonar takes all the measure taken in the last XX days, checks that the set of measures makes some senss (by testing the correlation rate), determines an estimated slope and displays it using the arrows.

It is possible to configure the number of days used by the tendencies. See Configure core plugin for more details.

Coding rules mapping

Sonar has its own classification of the coding rules. Currently Sonar manages 5 levels of activation for the rules : blocker, critical, major, minor and info. Since existing coding rules engines use their own levels, this page intends to describe the mapping between those and Sonar levels.

Checkstyle

Checkstyle uses 3 levels of severity : error, warning and info.

Import into Sonar

any rule not present or with an inactive level in the checkstyle.xml file during an import into Sonar will not be activated

Export out of Sonar

any rule not activated in Sonar will not be present in the Checkstyle.xml definition file resulting of an export

PMD

PMD uses 5 levels of priority, from 1 to 5

Import into Sonar

any rule not present in the PMD.xml file during an import into Sonar will not be activated

Export out of Sonar

any rule not activated in Sonar will not be present in the PMD.xml definition file resulting of an export

Findbugs

Findbugs uses 3 levels of priority, from 1 to 3

Import into Sonar

any rule not present in the Findbugs.xml file during an import into Sonar will not be activated

Export out of Sonar

Logically, here is what we should have...

any rule not activated in Sonar will not be present in the Findbugs.xml definition file resulting of an export

However, due to some strange behavior of Findbugs, Sonar does not set any priority in Findbugs when exporting. Otherwise some rules are not working.