Managing XML Analyzer Report (.plog file)

• Preliminary filtering of analysis results
• Converting the analysis results
• Notifying the developer team
• Summary

In this section we describe working in the Windows environment. Working in the Linux environment is described in the section "How to run PVS-Studio on Linux".

The analysis results that PVS-Studio generates as its output after it has finished checking a project (either from the Visual Studio plugin or in command-line batch mode) are typically presented as an XML log file (".plog"). Using direct integration of C++ analyzer to the build system to perform the analysis produces an unparsed 'raw' log file. You can view these files in the PVS-Studio plugin for Visual Studio or in the C and C++ Compiler Monitoring UI (Standalone.exe). These formats, however, are not convenient for viewing directly in a text editor, sending them via email, and so on. PVS-Studio package comes with a number of utilities that allow you to manage such log files in a number of ways.

Preliminary filtering of analysis results

The analysis results can be filtered even before a start of the analysis by using the No Noise setting. When working on a large code base, the analyzer inevitably generates a large number of warning messages. Besides, it is often impossible to fix all the warnings straight out. Therefore, to concentrate on fixing the most important warnings first, the analysis can be made less "noisy" by using this option. It allows completely disabling the generation of Low Certainty (level 3) warnings. After restarting the analysis, the messages from this level will disappear from the analyzer's output.

When circumstances will allow it, and all of the more important messages are fixed, the 'No Noise' mode can be switched off – all of the messages that disappeared before will be available again.

To enable this setting use the Specific Analyzer Settings page.

Converting the analysis results

When opening log file in a text editor, a user has to deal with XML markup or 'raw' unreadable log from the analyzer. To convert the analysis results into a more convenient format, use PlogConverter utility, which comes with PVS-Studio and can be found in the PVS-Studio installation directory ("C:\Program Files (x86)\PVS-Studio" by default). You can also download the source code of the utility.

Use the "'--help" option to display the basic information about the utility:

PlogConverter.exe --help

Let's take a closer look at the utility's parameters:

• --renderTypes (or -t): defines the possible formats into which the log files can be converted. The supported formats are Html, FullHtml, Totals, Txt, Tasks, Csv, and Plog. When not defined explicitly, the log file will be converted into all of these formats.
  • Html: converts the log file into an html file (convenient for automatic delivery to addressees on your mailing list).
  • FullHtml: converts the log file and the source files in html-files (you can view the analyzer report in browser with sorting by warnings and navigation along the code).
  • Txt: converts the log file into a text file.
  • Csv: converts the log file into a comma-separated file (convenient for viewing in Microsoft Excel, for example).
  • Totals: outputs the statistics on the issued warnings across the types (GA, OP, 64, CS, MISRA) and certainty levels. Detailed description of the levels of certainty and sets of diagnostic rules is given in the documentation section "Getting Acquainted with the PVS-Studio Static Code Analyzer".
  • Tasks: converts the log file into format that can be opened in QtCreator.
  • Plog: can be used to merges several plog xml files into one or transforms a raw unparsed log to parsed xml one.

You can combine different format options by separating them with "," (no spaces), for example:

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals

• --analyzer (or -a): filters the warnings by a specified mask. The mask format:

MessageType:MessageLevels

"MessageType" can be set to one of the following types: GA, OP, 64, CS, MISRA, Fail

"MessageLevels" can be set to values from 1 to 3

You can combine different masks by separating the options with ";" (no spaces), for example (written in one line):

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals
--analyzer=GA:1,2;64:1

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals 
-a GA:1,2;64:1

The command format reflects the following logic: convert ".plog" into Html, Csv, and Totals formats, keeping only the general-analysis warnings (GA) of the 1-st and 2-nd levels and 64-bit warnings (64) of the 1-st level.

• --excludedCodes (or -d): creates a list of warnings (separated with ",") that shouldn't be included into the resulting log file. For example, you don't want the V101, V102, and V200 warnings to be included (written in one line):

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals
--excludedCodes=V101,V102,V200

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals
-d V101,V102,V200

• --settings (or -s): defines the path to the PVS-Studio configuration file. PlogConverter will read your custom settings for the warnings you want turned off specified in the configuration file. This parameter in fact extends the list of the warnings that you want to be excluded defined by the "--excludedCodes" parameter.
• --srcRoot (or -r): specifies the replacer of the "SourceTreeRoot" marker. If the path to the project's root directory was replaced with the "SourceTreeRoot" marker (|?|), this parameter becomes obligatory (otherwise the utility won't be able to find the project files).
• --outputDir (or -o): defines the directory where the converted log files will be created. If not specified, the files will be created in the same directory where "PlogConverter.exe" is located.
• --outputNameTemplate (or -n): specifies the filename template without extension. All the converted log files will have the same name but different extensions (".txt", ".html", ".csv", ".tasks" or ".plog" depending on the "--renderTypes" parameter).
• --errorCodeMapping (or -m): to enable a display of CWE ID and MISRA ID for the found warnings: " -m cwe,misra".

Notifying the developer team

Once you have the converted log files, you can send them to other people involved in the development (team leaders, development manager, and so on). This process can be automated by including the analysis step into scheduled "night" builds, where the log file will be converted into the required format and sent to the specified addressees.

Here is an example. Once you have a "fresh" analysis report converted into an HTML file, run SendEmail utility. We are interested in the following basic parameters:

• -f : message sender;
• -t : message recipient. You can specify more than one recipient;
• -s : SMTP server;
• -u : message subject;
• -o username="" : username for authorization;
• -o password="" : password for authorization;
• -o message-charset=utf-8 : specifies the UTF-8 character set;
• -o message-file="PVS-Studio_report.html" : HTML file to be sent to the addressees.

You can also inform the developers by using the BlameNotifier utility, which comes with the PVS-Studio package. It is based on the following mechanism: on finishing the analysis, the analyzer generates a ".plog" file, which is then passed to BlameNotifier with some additional parameters. The utility finds the files with potential errors and forms an individual HTML report for each "guilty" developer. Another option is to send a complete log file with all the warnings sorted by the names of the developers responsible for the code that triggered those warnings.

BlameNotifier utility can be found in the PVS-Studio install directory ("C:\Program Files (x86)\PVS-Studio" by default). Use the "--help" option to display the basic information about the utility:

BlameNotifier.exe --help

BlameNotifier utility is available only if you have an Enterprise license. Please contact us to order a license.

Let's take a closer look at the utility's parameters:

• --VCS (or -v), obligatory parameter: the type of the version control system that the utility will be dealing with. Supported systems: Git, Svn, Mercurial.
• --recipientsList (or -r), obligatory parameter: the path to the text file with the mailing list. File description format:

# Recipients of complete log file
username_1 *email_1
...
username_N *email_N
# Recipients of individually assigned warnings
username_1 email_1
...
username_N email_N

Comments could be written with the "#" character. For recipients of the complete report, you need to add the "*" character before or after their email addresses. The complete log file will include all the warnings sorted by the developers.

• --server (or -x), obligatory parameter: SMTP server for mail sending.
• --sender (or -s), obligatory parameter: sender's email address.
• --login (or -l), obligatory parameter: username for authorization.
• --password (or -w): password for authorization.
• --port (or -p): mail delivery port (25 by default).
• --maxTasks (or -m): the maximum number of concurrently running blame-processes. By default or when set to a negative number, BlameNotifier will be using 2 * N processes (where N is the number of processor cores).
• --progress (or -g): turn logging on/off. Off by default.
• --enableSSL: enable SSL protocol. Off by default.

BlameNotifier can also use the parameters of PlogConverter, namely (see the descriptions in the corresponding section above):

• --analyzer (or -a);
• --excludedCodes (or -e);
• --srcRoot (or -t);
• --settings (or -c).

This feature allows you to filter the analysis results before sending them.

For example (written in one line):

BlameNotifier.exe "Drive:\Path\To\Plog" --VCS=Git 
--recipientsList="Drive:\Path\To\recipientsList.txt" 
--server="smtp.gmail.com" 
--sender=... --login=... --password=... 
--srcRoot="..." --maxTasks=40

Summary

Despite the built-in log-viewing features of PVS-Studio, there are other ways to view the analysis log. You can convert the XML file with the analyzer warnings into one of the formats that can be conveniently opened in other applications (html, txt, csv) by using PlogConverter utility. A converted report can be automatically sent on a daily basis to the persons involved in the development to inform them about the analyzer warnings (SendEmail utility). In addition, BlameNotifier utility can be used to automate the process of finding the developers responsible for writing code that triggered certain warnings. BlameNotifier will send html messages to these developers and also prepare a complete report for "special" persons with the warnings sorted by the "guilty" developers.