Adding custom reports based on metrics you define

Klocwork allows you to define your own custom metrics and report on them in Klocwork Static Code Analysis. There are three steps in this process:

1. Define a custom metric in a user-defined metrics file (.ume ).
2. Import your user-defined metrics file into a Klocwork server project.
3. Define a custom metrics report in the metrics report configuration file (metrics.xml).

Create the user-defined metrics file (.ume)

You can create a custom metric and apply it to a specific source file. For example, you might want to track source code changes, such as the number of added, deleted, or changed lines.

The user-defined metrics file is a text file with the extension .ume. In a user-defined metrics file, each line represents the definition for one metric for one source file.

The format of a line is:

<metric_name>;<metric_value>;<file_path>

where:

• <metric_name> can be any name (up to 255 symbols). The semicolon (;) is not allowed.
• <metric_value> is any numeric value that represents the metric's value for the specified file. You collect this data from your source code (for example, through a script).
• <file_path> is the path to the source file

Example

LINES_ADDED;5;c:\my_project\src\main.cpp
LINES_ADDED;15;c:\my_project\src\driver.cpp

These examples define two metrics that specify the number of lines added to each source file since the last Klocwork analysis.

Applying the user-defined metrics file to the analysis

To apply your new configuration file to the integration build analysis, import it into a project or the projects_root.

Edit the metrics.xml file

To add your custom reports to the metrics.xml file, so that they are visible in Static Code Analysis:

1. Back up the following file:

   <projects_root>/config/metrics.xml

2. Open the original metrics.xml file for editing.
3. Copy and paste one of the <metric> elements in the appropriate category.
4. Edit the elements as required.

   For reports in the TotalMetricValue category, edit the following elements:

   <name>

   <description>

   <custom_metric_names>

   For reports in the EntityCountOverThreshold category, edit the following elements:

   <name>

   <description>

   <custom_metric_names>

   <entityKids>

   <default_threshold>

5. Save the file.
6. Restart the Klocwork Server with kwservice restart or Windows Services Administration.

   The changes you have made are visible to all Static Code Analysis users when they log in, or when they refresh the Reports page.

Walk-through

We'll call our sample project my_project. It contains two files, main.cpp and driver.cpp. We want to define two custom metric reports for this project:

• the number of lines added to each source file since the last Klocwork analysis
• the number of files in the project in which the number of lines added since the last Klocwork analysis exceeds 10

1. Create a text file named my_metrics.ume and add these lines to the file (a script could provide this information for your source code):

   LINES_ADDED;5;c:\my_project\src\main.cpp

   LINES_ADDED;15;c:\my_project\src\driver.cpp

   These lines show that five lines were added to main.cpp and 15 lines were added to driver.cpp since the last analysis.

2. Import the file into the project:

   kwadmin import-config my_project C:\Klocwork\my_metrics.ume
   

3. Define a custom metrics report for each of these user-defined metrics.

   For the first custom report, we want the short name "Lines Added" to appear in the Reports menu of Static Code Analysis, and the title "Lines Added to File" to appear at the top of the report.

   We add the following text to the metrics.xml file in the element <category catid="TotalMetricValue">:

   <metric>

   <name>Lines added</name>

   <description>Lines Added to File</description>

   <custom_metric_names>LINES_ADDED</custom_metric_names>

   <enable>true</enable>

   </metric>

4. For the second custom report, we want the short name "Line addition threshold" to appear in the Reports menu of Static Code Analysis, and the title "Number of Files with More than 10 Lines Added" to appear at the top of the report.

   Add the following text to the metrics.xml file in the element <category catid="EntityCountOverThreshold">:

   <metric>

   <name>Line addition threshold</name>

   <description>Number of Files With More Than {threshold} Lines Added</description>

   <custom_metric_names>LINES_ADDED</custom_metric_names>

   <entityKids>1</entityKids>

   <default_threshold>10</default_threshold>

   <enable>true</enable>

   </metric>

5. Save the file.
6. Restart the Klocwork Server with kwservice restart or Windows Services Administration.
7. Run a Klocwork integration build analysis on my_project.
8. To verify that our changes took effect, log in to Static Code Analysis.
9. Click Reports for your project.
10. Click Create a new report.
    Note: If you were already viewing the report types, refresh your browser to pick up the changes to metrics.xml.
11. The report types are displayed on the right. Scroll down and click see more.

    Our list now includes the Lines added and Line addition threshold report types.

12. Select Line addition threshold to ensure that the default threshold is set at 10.