Работа с XML отчётом (.plog файл)


В данном разделе рассматривается работа в среде Windows. Работа в среде Linux описана в разделе "Как запустить PVS-Studio в Linux".

Результатом проверки проекта с помощью PVS-Studio (плагин Visual Studio, или же в режиме из консоли) обычно является XML файл отчета анализатора (".plog"). При использовании прямой интеграции анализатора в сборочную систему, результатом работы является необработанный вывод C++ анализатора. Такие файлы можно просматривать через плагин PVS-Studio для Visual Studio, либо через приложение C and C++ Compiler Monitoring UI. Эти форматы отчёта, однако, не удобны, например, для прямого просмотра в текстовом редакторе, рассылки по электронной почте и т.п. В состав дистрибутива PVS-Studio входит ряд утилит, позволяющих различными способами обрабатывать файлы отчёта анализатора.

Предварительная фильтрация результатов анализа

Отчёт анализатора можно отфильтровать ещё перед запуском анализа с помощью настройки No Noise. При работе на большой кодовой базе, анализатор неизбежно генерирует большое количество предупреждений. При этом, часто нет возможности поправить все предупреждения сразу. Для того, чтобы иметь возможность сконцентрироваться на правке наиболее важных предупреждений, можно сделать анализ менее "шумным" с помощью данной настройки. Она позволяет полностью отключить генерацию предупреждений низкого уровня достоверности (Low Certainty, 3-ий уровень предупреждений). После перезапуска анализа, сообщения этого уровня полностью пропадут из вывода анализатора.

Когда обстоятельства позволят и более существенные предупреждения анализатора будут исправлены, можно выключить режим No Noise – при следующем анализе все пропавшие ранее предупреждения станут вновь доступны.

Для включения этой настройки используйте окно Specific Analyzer Settings.

Конвертация результатов анализа

Открыв отчет с помощью текстового редактора, пользователь столкнется с XML-разметкой или нечитаемым "сырым" выводом анализатора. Для наглядного представления результатов анализа можно воспользоваться утилитой PlogConverter, поставляемой в дистрибутиве PVS-Studio. Утилиту PlogConverter можно найти в установочной директории PVS-Studio (по умолчанию это путь "C:\Program Files (x86)\PVS-Studio"). Вы также можете скачать исходный код утилиты.

Флаг "--help" выведет основную информацию об утилите:

PlogConverter.exe --help

Рассмотрим детально каждый параметр утилиты:

  • --renderTypes (или -t): задает возможные варианты конвертации отчета. Поддерживаемыми форматами являются Html, FullHtml, Totals, Txt, Csv, Tasks, Plog. Если задан неявно, то отчет конвертируется во все форматы
    • Html: конвертирует сообщения анализатора в html-файл (удобно использовать в автоматических рассылках на email).
    • FullHtml: конвертирует сообщения анализатора и исходные файлы в html-файлы (можно просматривать отчёт анализатора в браузере с сортировкой по сообщениям и навигацией по коду).
    • Txt: конвертирует сообщения анализатора в текстовый файл.
    • Csv: конвертирует сообщения анализатора в формат файла с разделителями (удобно читаем, например, в Microsoft Excel).
    • Totals: выводит суммарную информацию о количестве предупреждений разных типов (GA, OP, 64, CS, MISRA) и разных уровней достоверности. Детальное описание уровней достоверности предупреждений и наборов диагностических правил приведено в разделе документации "Знакомство со статическим анализатором кода PVS-Studio".
    • Tasks: конвертирует сообщения анализатора в формат файла для просмотра в QtCreator.
    • Plog: позволяет соединить несколько xml отчетов в один или преобразовать необработанный вывод анализатора в xml лог.

Возможна комбинация разных форматов через "," (без пробелов), например:

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

или

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals
  • --analyzer (или -a): производит фильтрацию предупреждений согласно маске. Маска фильтрации имеет следующий вид:
MessageType:MessageLevels

"MessageType" может принимать один из следующих типов: GA, OP, 64, CS, MISRA, Fail

"MessageLevels" может принимать значения от 1 до 3

Возможна комбинация разных масок через ";" (без пробелов), например (одной строкой):

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

или

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

Запись соответствует следующей логике: сконвертировать ".plog" в Html, Csv, Totals отчеты, оставив только предупреждения общего назначения (GA) 1-ого и 2-ого уровней и 64-битные ошибки (64) 1-ого уровня.

  • --excludedCodes (или -d): задает список предупреждений (через ","), которые не следует включать в результирующий отчет. Например, нужно убрать предупреждения V101, V102, V200 (одной строкой):
PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals
--excludedCodes=V101,V102,V200

или

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals
-d V101,V102,V200
  • --settings (или -s): задает путь к файлу конфигурации PVS-Studio. PlogConverter прочитает настройки отключенных предупреждений из переданного файла настроек, указанных в конфигурации. По сути, этот параметр расширяет список отключаемых предупреждений параметра "--excludedCodes".
  • --srcRoot (или -r): задает замену "SourceTreeRoot" маркера. Если при проверке путь до корневого каталога проекта был заменен на "SourceTreeRoot" маркер (|?|), то этот параметр становится обязательным (иначе файлы проекта не будут найдены).
  • --outputDir (или -o): задает директорию, куда будут сохранены конвертированные отчеты. Если параметр не задан, то файлы записываются рядом с "PlogConverter.exe".
  • --outputNameTemplate (или -n): задает шаблонное имя файла без расширения. Все конвертированные отчеты будут иметь одно и то же имя, но с разными расширениями (в зависимости от "--renderTypes", это могут быть ".txt", ".html", ".csv", ".tasks", ".plog").
  • --errorCodeMapping (или -m): включить отображение CWE ID и MISRA ID для найденных предупреждений: " -m cwe,misra".

Оповещение разработчиков

После генерации конвертированные отчеты могут быть разосланы нужным людям (лидерам команд, руководителю разработки и т.д.). Процесс можно автоматизировать, поставив проверку проекта на "ночные" сборки, сконвертировав отчет анализатора в нужный вид и разослав интересующим персонам.

Продемонстрируем пример. После получения "свежего" отчета и его конвертации в HTML-форму используем утилиту SendEmail. Основными используемыми параметрами будут:

  • -f : задает отправителя сообщения;
  • -t : задает получателя сообщения. Получателей можно задать более одного;
  • -s : SMTP-сервер;
  • -u : тема письма;
  • -o username="" : имя пользователя для авторизации;
  • -o password="" : пароль пользователя для авторизации;
  • -o message-charset=utf-8 : установить кодировку сообщения как UTF-8;
  • -o message-file="PVS-Studio_report.html" : HTML-отчет, который рассылается адресатам.

Также возможен иной способ оповещения разработчиков, основанный на использовании утилиты BlameNotifier, поставляемой в дистрибутиве PVS-Studio. Суть работы утилиты следующая: после проверки проекта генерируется отчет в формате ".plog". Отчет подается на вход BlameNotifier с указанием дополнительных параметров; утилита находит файлы, в которых, вероятно, допущены ошибки и формирует HTML-отчет на каждого "виновного" разработчика. Также возможен вариант рассылки полного отчета: внутри него будут содержаться все предупреждения, отнесенные к каждому "виновному" разработчику.

Утилиту BlameNotifier можно найти в установочной директории PVS-Studio (по умолчанию это путь "C:\Program Files (x86)\PVS-Studio"). Флаг "--help" выведет основную информацию об утилите:

BlameNotifier.exe --help

Утилита BlameNotifier доступна только при наличии Enterprise лицензии. Для заказа лицензии, пожалуйста, напишите нам.

Рассмотрим каждый параметр утилиты:

  • --VCS (или -v), обязательный параметр: тип системы контроля версий, с которой будет работать утилита. Поддерживаемые системы: Git, Svn, Mercurial.
  • --recipientsList (или -r), обязательный параметр: путь до текстового файла, содержащего список получателей отчетов. Формат описания файла выглядит следующим образом:
# Получатели полного отчёта
username_1 *email_1
...
username_N *email_N
# Получатели собственных ошибок
username_1 email_1
...
username_N email_N

Закомментировать строку можно символом "#". У получателей полных отчетов надо добавить символ "*" в начале или в конце email адреса. Полный отчет будет включать все предупреждения, отсортированные по разработчикам.

  • --server (или -x), обязательный параметр: SMTP-сервер для отправки отчетов.
  • --sender (или -s), обязательный параметр: email адрес отправителя писем.
  • --login (или -l), обязательный параметр: имя пользователя для авторизации.
  • --password (или -w): пароль пользователя для авторизации.
  • --port (или -p): номер порта для отправления писем. По умолчанию указан порт N25.
  • --maxTasks (или -m): максимальное число параллельно запущенных blame-процессов. По умолчанию, или если задано отрицательное число, BlameNotifier будет использовать 2 * N процессов (где N - число ядер процессора).
  • --progress (или -g): включить или отключить логгирование. По умолчанию логгирование выключено.
  • --enableSSL: включить использование протокола SSL. По умолчанию выключено.

Также BlameNotifier использует параметры PlogConverter, а именно (описание было приведено выше):

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

Это позволяет отфильтровать результаты анализа перед рассылкой.

Пример использования (одной строкой):

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

Заключение

Несмотря на встроенные возможности просмотра логов в PVS-Studio, существуют и иные методы взглянуть на отчет. XML-файл с предупреждениями анализатора можно преобразовать в один из удобочитаемых (html, txt, csv) форматов с помощью утилиты PlogConverter. Сконвертированный отчет можно включить в ежедневную рассылку с целью оповещения разработчиков об предупреждениях анализатора (например, использовав утилиту SendEmail). Также, с помощью утилиты BlameNotifier можно автоматизировать процессы поиска разработчика, который мог внести в код инструкции, с точки зрения анализатора кажущиеся подозрительными. BlameNotifier разошлет нужным разработчикам письма в формате html с подотчетными им предупреждениями, а также подготовит отчет для "специальных" людей, в котором предупреждения уже размечены по "виновным".


Найденные ошибки

Проверено проектов
355
Собрано ошибок
13 303

А ты совершаешь ошибки в коде?

Проверь с помощью
PVS-Studio

Статический анализ
кода для C, C++, C#
и Java

goto PVS-Studio;