Converting analysis results (PlogConverter tool)

• PlogConverter tool
  • Parameters
  • Exit codes
• Automatic notification about analyzer warnings

This section covers converting logs for Windows. Converting logs for Linux and macOS is described in the document "How to run PVS-Studio on Linux and macOS".

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. The PVS-Studio distribution includes, among other things, the PlogConverter utility, which allows you to convert analysis results to other formats.

PlogConverter tool

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.

Parameters

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, Plog, and TeamCity. 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.
  • TeamCity: converts the log file into a file for viewing in the TeamCity CI.

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".
• --indicate-warnings (or -w): sets the PlogConverter utility's exit code to '2' if after log filtration the filtered output file (files) still contains warnings.
• --pathTransformationMode (or -R): sets the path transformation mode when converting the report. The option requires "--srcRoot". Possible values:
  • toAbsolute - converts paths to absolute;
  • toRelative - converts paths to relative.

Exit codes

The PlogConverter utility defines several non-zero exit codes, which do not necessarily indicate some issue with the operation of the tool itself, i.e. even when the tool returns something other when zero it does not always mean that the tool has 'crashed'. Here's the description of all possible exit codes, that PlogConverter can return.

• '0' - conversion finished successfully;
• '1' - errors were encountered during generation of one of the output files;
• '2' - output contains non-suppressed warnings after filtration. This exit code will be generated only when using converter with "--indicate-warnings" (-w) flag;
• '3' - general (nonspecific) error in the converter's operation, a possible handled exception. Usually, this means an error inside the PlogConverter;
• '4' - some of the command line arguments passed to the tool were incorrect or one of the files, passed as an argument, hadn't been found, or doesn't exist;

Automatic notification about analyzer warnings

The PVS-Studio distribution includes the BlameNotifier tool, which allows you to notify developers who have committed code in the repository that triggered analyzer warnings. You can also configure notifications about all detected warnings for a specific group of people (this can be useful, for example, for managers and team leads).

The following documentation section describes the ways how to use the BlameNotifier tool: "Notifying the developer teams (blame-notifier utility)".

Note. The blame-notifier tool is available only if you have an Enterprise license. To order the license, please, write to us.