In this article, we will discuss how you can create Klocwork Metric Reports based on custom metrics.
The end result is very similar to our article on creating Klocwork Metric Reports using the built-in Klocwork metrics.
However, this article focuses on creating reports based on custom metrics that are NOT computed by a Klocwork analysis. Therefore, it is assumed that you already have a script that can compute the metric values you are interested in, which Klocwork will then use to create reports.
Step 1 – Create the user-defined metrics file (.ume)
The user-defined metrics file is where you define your custom metrics. Klocwork only uses one .ume file per project. Alternatively, you can have the .ume file applied to all projects if you wish (shown in Step 2)
Here, we define the name, value, and source file to which the metric applies. The format of this file is: <metric_name>;<metric_value>;<file_path>
- <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
Here is an example of a custom metric in the .ume file:
These examples define two metrics that specify the number of lines added to each source file since the last Klocwork analysis.
Here, we hard coded the values 5, and 15. In reality, we would have a separate script that would calculate the <metric_value>.
Step 2 – Import the .ume file to the Klocwork Server
- To import the .ume file into a specific project, run the command
- kwadmin import-config <project_name> <.ume file>
- To import the .ume file for all projects, run the command
- kwadmin import-config workspace <.ume file>
Step 3 – Edit the metrics.xml file
Now that we have told Klocwork what our custom metrics are, we can now edit the metrics.xml file to generate custom reports based on those metrics.
This is quite similar to how we dealt with editing the xml file for the default Klocwork metrics, with only slight differences.
Let’s say we have a script that counts the number of lines added to each source file since the last Klocwork analysis. Assume we have already defined the metric in the .ume file, and imported the .ume file into the project.
With this metric, we would like to generate two reports that count
- 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
Continuing with our example, here is how the TotalMetricValue category should look like:
And here is how the EntityCountOverThreshold category should look like:
Notice how we are using the new element <custom_metric_names></custom_metric_names> as opposed to the <kids></kids> element, which is used only for the built-in Klocwork metrics.
Step 4 – Restart the Klocwork server
Save the edited metrics.xml file and restart the Klocwork server by running the command: kwservice -r <projects_root> restart
Step 5 – Run an integration analysis on the project
During your Klocwork build process your custom metrics scripts should be executed, which should then output a .ume file as structured in Step 1.
After the file is generated, the build process should subsequently run the command
kwadmin import-config <.ume file>
to ensure that the updated .ume file will be used to generates reports on the Klocwork server.
Step 6 – View the reports
- Click on the ‘Reports‘ tab.
- Click ‘Create a new report‘
- Scroll down to ‘show more‘
- Click on one of the custom reports you have defined.
And that should be it! Please feel free to ask any questions by using the contact form below.