Changing the thresholds for reported metrics
Changing the thresholds for reported metrics
Klocwork can detect and report on metrics threshold violations that you set based on your organization's standards and priorities. The default metrics thresholds configuration file produces a report that covers a few basic metrics. By modifying this configuration file, however, you can have Klocwork report on those errors most relevant to your code quality objectives.
About the default metrics thresholds configuration file
The metrics thresholds configuration file is a text file in which you set the thresholds you want Klocwork to report. If a metrics threshold is violated, Klocwork reports the violation. Each line in the configuration file sets one threshold.
Here are a few examples of the types of metrics thresholds you could set:
- Number of lines of code in a file should be less than or equal to 5000
- Complexity of a file <=20
- No more than one class defined in the file
Note: When Klocwork reports a metric-threshold, any non-ASCII characters in the error code are replaced by "_" (underscore). However, non-ASCII characters still display (in UTF-8 encoded files) in the category name and the message. For more information, see Klocwork support for non-ASCII encoding. The metrics thresholds configuration file, called metrics_default.mconf, is located either: - in the default location, <Klocwork_install>/config
- or
- in <projects_directory>/config (for integration projects that have the projects_root directory in a non-default location)
The metrics_default.mconf file shows some examples of the types of threshold violation rules that can be created.
Editing the metrics thresholds configuration file
- Identify the metrics thresholds you want to set.
- Navigate to the directory that contains the configuration files, make a copy of the metrics_default.mconf file and save it with the name of your choice or create a new metrics thresholds configuration file with the name and location of your choice. It must have the file extension .mconf .Note: If you modify the existing configuration file, make a backup copy first.
- In your new or modified default metrics thresholds configuration file, modify the content as required using the syntax outlined in the next section and Creating categories of metric threshold rules.
- Save the file.
Syntax of metric threshold rules
Each line of the metric thresholds configuration file represents one metric threshold for which you want Klocwork to detect violations. Each metric threshold rule in the file has the following fields:
- Name;Entity-type;Metric-expression;Error-threshold;Warning-threshold
The following sections detail each field.
Comments and blank lines are allowed in the configuration file syntax. Use the pound symbol (#) at the beginning of comment lines so they are not read as rules.
#!alias MetricCode = <expression>
Following this comment, all occurrences of "MetricCode" are textually substituted with <expression>.
Name
Name is a simple description of the violation that appears in the report if such a violation is detected, for example, Number of class declarations. For a full list, see the Name column of the tables in Metrics reference. The name must be unique among metric rule names used in all .mconf files.
Entity-type
Entity-type is the software entity for which the metric threshold is applicable. If you want the same threshold to apply to more than one software entity, you can specify several in a comma-separated list. For example:
- Number of paths (NP);FUNCTION,METHOD;NOINDPATHS;10;7
The following tables show which entity types you can use with each of the metric categories.
Applicable entity types for each metric category: C/C++
| Metric category | Applicable entity types |
|---|---|
| File-level metrics | FILE |
| Class-level metrics | CLASS, TYPE, CLASS-TEMPLATE |
| Function- and method-level metrics | FUNCTION, CLASS-METHOD, FUNCTION-TEMPLATE, TEMPLATE-MEMBER |
TYPE in class level threshold rules stands for structs and unions.
TEMPLATE-MEMBER in function-level metric threshold rules stands for class-template methods.
Applicable entity types for each metric category: Java
| Metric category | Applicable entity types |
|---|---|
| File-level metrics | FILE |
| Class-level metrics | CLASS |
| Function- and method-level metrics | CLASS-METHOD |
Metric-expression
Metric-expression can be either of the following:
- a simple metric code such as LOC_FILE (lines of code per file) from the "Metric code" column of the file-level metrics table in Metrics reference.
- a complex expression containing logical or arithmetic operations and function calls (see 'Function call values' below, for example: log(LOC/NOROUTINES)
Error-threshold
Error-threshold is a number that represents the threshold for the metric. See Number values (below) for more information. It may be prefixed by a logical operation such as <, <=, or >=. See Logical operations below for more information. If only a number is entered in this field, the default operation applied is "greater than" (>). Violation of this metric would be reported as an error. For example, if you set the error threshold for the lines of code per file metric at <100, an error would be reported if the number of lines of code in a file (LOC_FILE) were less than 100.
Warning-threshold
Warning-threshold is a number that represents the threshold for the metric defined in the expression. The number may be prefixed by a logical operation such as <, <=, or >=. If only a number is entered in this field, the default operation applied is "greater than" (>). Violations of this metric would be reported as a warning. For example, if you set the warning threshold for the lines of code per file metric at <100, a warning would be reported if the number of lines of code in a file (LOC_FILE) were less than 100.
If a metric exceeds both the warning and the error thresholds, only the error message is reported.
Example of full metric threshold rule
- Percent of comments;FILE;LINESCOMM/LOC_FILE*100;<5;<10
Function call values
FunctionCall can have the following functions:
| abs(X) | Returns the absolute value of its argument |
|---|---|
| atan2(X,Y) | Returns the arctangent of Y/X in the range -pi to pi |
| cos(X) | Returns the cosine of X (expressed in radians). |
| exp(X) | Returns e (the natural logarithm base) to the power of X. |
| int(X) | Returns the integer portion of X. |
| log(X) | Returns the natural logarithm (base e) of X |
| sin(X) | Returns the sine of X (expressed in radians). |
| sqrt(X) | Returns the square root of X. |
Number values
Number can be any of the following:
- integer is defined as a real whole number. For example, 123 or 1000.
- decimal is defined as a number with a decimal point in it. For example, 123.45 or.6.
- floating point scientific notation is defined as a number between 1 and 10 multiplied by 10 to some power. For example, 2.3E-10 or 3E-5.
Logical operations
Logical operations can be any of the following:
| < | less than |
|---|---|
| <= | less than or equal to |
| equal to | |
| > | greater than (default when only a number is specified in a threshold field) |
| >= | greater than or equal to |
| != | not equal to |
Creating categories of metric threshold rules
If you choose, you can organize your metric threshold rules into categories with names you find meaningful.
You can name the categories as you wish. Note, however, that all metrics grouped into one category are assigned the same error or warning severity level, so they should be of equal importance in terms of how important it is to address the detected violations.
Specifying categories in the configuration file
Categories are specified in the configuration file with a line like the following:
- WARNING.SEVERITY=7 ERROR.SEVERITY=3 WARNING.CATEGORY="User-defined warning category 1" ERROR.CATEGORY="User-defined error category 1"
where
- WARNING.SEVERITY= precedes a numerical value that represents the seriousness of the violation with 1 being the most serious and 10 being the least serious. Violations of rules in this category will be shown as warnings if the value in the warning field of a rule is exceeded.
- ERROR.SEVERITY= precedes a numerical value that represents the seriousness of the violation with 1 being the most serious and 10 being the least serious. Violations of rules in this category will be shown as errors if the value in the error field of a rule is exceeded.
- WARNING.CATEGORY= precedes your name for the category of rules. The name must be enclosed in quotation marks as follows: "category name".
- ERROR.CATEGORY= precedes your name for the category of rules. The name must be enclosed in quotation marks as follows: "category name".
The default configuration file contains three placeholder "user-defined warning categories".
Examples of setting a metrics threshold
The following table describes and shows the syntax of some typical metrics thresholds to include in a Klocwork report. Remember that you can change the text of the Name field (which describes the metrics threshold).
Example 1
Rule intent: At the file level, show the percentage of comment lines. If less than five percent of lines are comments, issue an error. If less than 10% but more than five percent of lines are comments, issue a warning.
Rule syntax: Name;Kind;Expression;Error threshold;Warning threshold
Percent of comments;FILE;LINESCOMM/LOC_FILE*100;<5;<10
Example 2
Rule intent: Show the number of calls to unique functions. If there are 20 or more, issue an error. If there are 15 to 19, issue a warning.
Rule syntax: Name;Kind;Expression;Error threshold;Warning threshold
Number of unique calls (UCT);FUNCTION,CLASS-METHOD;NOCALLS;20;15
Example 3
The following example shows three stages. The source code file shows what you begin with:
1 /* function main */
2 main(){
3 printf("Hello world\n");
4 }
5
6 hello(){
7 // tbd
8 }
9 test(int a){
10 return 1;
11 }
12
Change the threshold in the Metrics thresholds configuration file:
Number of lines of code of function;FUNCTION;LOC_FILE;>100;>30 Cyclomatic complexity (VG);FUNCTION;CYCLOMATIC;20;8 Empty function;FUNCTION;NOOPUSED|NORET;==3.14;==0
After your .mconf file is imported and analyzed, the default kwcheck output will be:
1 <path>/example2.c:6 METRICS.W.Empty_function Analyze Violated metric "Empty_function": hello 0==0
Specifying sizes for built-in types
When you run a Klocwork analysis, it calculates all supported metrics and stores them in the metric.dat file in your tables directory. The reports, however, only show violations of metrics thresholds for which there are rules in the metrics thresholds configuration file.
If you want Klocwork to report on more metrics, you need to write additional metric threshold rules and add them to your metrics thresholds configuration file.
Before you can write new rules involving the following metrics, however, you may need to provide additional information to ensure that the metrics are calculated correctly. The required information is beyond the scope of what Klocwork can discover directly from your source code.
The following metrics that calculate the number of bytes of certain entities in your code may only be calculated correctly if you use additional Klocwork options.
- BYTESGLDATADECL
- BYTESDATADECL
- BYTESLOCDECL
- BYTESPARMS
- BYTESPAROTHER
Calculation of these metrics depends on stored information about the size, in bytes, of built-in types in your software system. If the size of your built-in types matches the default sizes, Klocwork correctly calculates these metrics every time you run it.
Klocwork uses the following default sizes for built-in types:
Windows
char;1signed char;1 unsigned char;1 short int;2 signed short int;2 unsigned short int;2 int;4 signed int;4 unsigned int;4 long int;4 signed long int;4 unsigned long int;4 __int8;1 __int16;2 __int32;4 __int64;8 __wchar_t;2 float;4 double;8 long double;8 <pointer>;4 <unknown type>;4
Unix:
char;1signed char;1 unsigned char;1 short int;2 signed short int;2 unsigned short int;2 int;4 signed int;4 unsigned int;4 long int;4 signed long int;4 unsigned long int;4 long long int;8 signed long long int;8 unsigned long long int;8 float;4 double;8 long double;12 <pointer>;4 <unknown type>;4
If the size of your built-in types do not match these default sizes, you need to create a "size of types" file and use this configuration file during Klocwork analysis:
- Create a text file with any name and location you choose. It must have the file extension .szt.
- In each line of the file, specify a type and a type size using the following syntax:
- <type_name>;<type_size>
- where
- <type_name> is the name of the built-in type
- <type_size> is the size of the type, in bytes
- Include these two predefined type names in your file:
- 0_TYPE_POINTER is used to specify the size of pointers or references
- 0_TYPE_UNKNOWN is used to specify the size of unknown built-in types
- To apply your new configuration file to the integration build analysis, import it into a project or the projects_root.
Applying the metrics threshold configuration file to the analysis
To apply your new configuration file to the integration build analysis, import it into a project or the projects_root.