Диагностика работы анализатора PVS‑Studio

• Термины (используются далее по тексту)
• Когда использовать
• Быстрый старт
  • Как это работает
• Включение логирования и его опции
  • Конвертация сырого лога вручную (pvs-diag-collector convert)
• Как читать структурированный лог
  • Основные разделы
  • Аномалии
  • Типовые задачи
  • Просмотр лога в редакторе с подсказками по полям
  • JSON схемы структурированных логов утилит из дистрибутива PVS-Studio
• Приватность и требования безопасности
• Что отправлять в техническую поддержку
• FAQ
  • Где находятся логи?
  • Можно ли посмотреть содержимое лог-файлов?
  • Я не вижу структурированный JSON-лог. Что делать?
  • Почему сырые логи остались после анализа?
  • Можно ли использовать лог в автоматизации (CI/скрипты)?
  • Как удобнее всего изучать лог?

Диагностическое логирование предназначено для быстрого сбора воспроизводимой информации о запуске анализатора: фактические параметры, окружение, результат выполнения, а также сведения о том, какие файлы были проанализированы или пропущены.

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

Если вы столкнулись с проблемами в работе анализатора (падениями, некорректными завершениями работы и прочими ситуациями, которые мешают вам использовать PVS-Studio), то при обращении в техническую поддержку стоит прикрепить полученные логи. Обратиться в техническую поддержку можно через форму на сайте.

Термины (используются далее по тексту)

Структурированный лог — текстовый файл, содержащий диагностическую информацию в формате JSON. Пригоден для машинной обработки.

Сырой лог — текстовый файл с промежуточной информацией, из которого формируется структурированный лог. Имеет суффикс *-raw.PVS-Studio.log. Не предназначен для использования при самостоятельной диагностике проблем.

Анализатор (frontend) — pvs-studio-analyzer (CompileCommandsAnalyzer) и PVS-Studio_Cmd;

Исполнитель (анализа; запускается анализатором) — pvs-studio.

Когда использовать

Рекомендуется включать диагностическое логирование, если:

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

Быстрый старт

1) Запуск анализа с формированием структурированного лога:

# Для pvs-studio-analyzer (CompileCommandsAnalyzer):
pvs-studio-analyzer analyze <ваши_обычные_флаги_анализа> \
  --enable-logging ./pvs-diag.json

# Для PVS-Studio_Cmd:
PVS-Studio_Cmd <ваши_обычные_флаги_анализа> \
  --enable-logging ./pvs-diag.json

После выполнения появятся:

• структурированный лог: ./pvs-diag.json;
• сырой лог анализатора (в случае аварийного завершения): ./*-raw.PVS-Studio.log.

2) Если структурированный лог не сформировался (из-за какой-либо ошибки), то конвертацию можно запустить вручную:

pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json

Как это работает

• Вы запускаете анализатор со включённым логированием;
• Во время работы диагностические данные записываются в сырые логи;
• По завершении анализа формируется структурированный JSON‑лог;
• Если на этапе формирования JSON что-то пошло не так, то сырые логи остаются на диске. Их можно сконвертировать вручную с помощью утилиты pvs-diag-collector или отправить в поддержку.

Включение логирования и его опции

--enable-logging <file_path> — обязательный флаг для включения логирования и сохранения структурированного JSON-лога в указанный файл.

Опции логирования

Опции задаются флагом --logging-options <option1,option2,...>. Значения передаются через запятую, без пробелов.

Корректно:

--logging-options skip-sensitive,dump-intermediate-files

Некорректно:

--logging-options skip-sensitive, dump-intermediate-files

Доступные опции:

Примеры:

# Для pvs-studio-analyzer (CompileCommandsAnalyzer):
pvs-studio-analyzer analyze <ваши_обычные_флаги> \
  --enable-logging ./pvs-diag.json \
  --logging-options skip-sensitive,dump-intermediate-files,embed-runs

# Для PVS-Studio_Cmd:
PVS-Studio_Cmd <ваши_обычные_флаги> \
  --enable-logging ./pvs-diag.json \
  --logging-options skip-sensitive,dump-intermediate-files,embed-runs

Конвертация сырого лога вручную (pvs-diag-collector convert)

pvs-diag-collector — это утилита для сбора/обработки логов и сопутствующих артефактов работы анализатора PVS-Studio.

Команда convert утилиты pvs-diag-collector преобразует сырой лог анализатора (*-raw.PVS-Studio.log) в структурированный.

Использование

pvs-diag-collector.exe convert [FILE] [-i <FILE>] [-o <FILE>]
                               [--embed-runs] [-j <NUM>]

Опции утилиты

Примеры

# Вывод в файл с подробными сведениями о запусках исполнителей
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json              \
                           -–embed-runs
# Вывод в файл
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \
                           --output ./pvs-diag.json
# Вывод в консоль
pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log

Коды возврата

• 0 — успех;
• 1 — ошибка (также будет выведен текст ошибки).

Как читать структурированный лог

Ниже описаны основные поля и подсказки для типовых проблем. Полное описание всех полей находится в JSON schema (см. раздел про просмотр в редакторе).

Основные разделы

Обычно полезно начать с:

• basicPerformance — время и память;
• configuration — фактические настройки работы анализатора;
• environment — ОС/платформа/переменные окружения;
• input — фактические аргументы запуска, используемые настройки и конфигурации;
• output — код возврата, stdout/stderr, признаки проблем;
• runs — какие файлы анализировались/пропускались/завершились с ошибкой.
• utility — какая утилита сформировала лог, её версия и путь до неё.

Аномалии

В процессе конвертации сырых логов анализаторов могут детектироваться "аномалии" — это подсказки о потенциальных проблемах (например, наличие вывода в stderr, неуспешные статусы, несоответствие версий и т.п.).

Их следует искать в output.anomalies.

Типовые задачи

В данном разделе указаны типовые сценарии использования логирования и наиболее вероятные поля лога, на которые стоит обратить внимание.

Анализ завершился ошибкой / аварийно

• output.returnCode
• output.stderr и output.stdout
• output.anomalies (если присутствуют)

Файл не попал в анализ (пропущен)

• runs.skipped[]
• runs.skipped[].sourceFilePath
• runs.skipped[].skipReason
• настройки путей/исключений в input

Нужно подтвердить фактическую конфигурацию запуска

• input.arguments
• конфигурационные файлы/настройки в configuration
• (при наличии) runs.executed[].stages.analysis.details разделы итоговой конфигурации в логах исполнителя

Проблема с производительностью

• basicPerformance.elapsedTime
• basicPerformance.peakMemoryConsumption

Просмотр лога в редакторе с подсказками по полям

Структурированный лог содержит поле $schema. Если редактор может получить JSON schema, он будет:

• показывать описания полей при наведении;
• подсказывать допустимые значения;
• подсвечивать ошибки типов и структуры.

Рекомендуемый сценарий

• Откройте JSON-лог в редакторе кода (например, Microsoft Visual Studio Code).
• Убедитесь, что значение $schema доступно (в корпоративной сети/интернете — согласно вашей политике). Если файл по указанной ссылке недоступен, то вы можете изменить ссылку на тот же файл в дистрибутиве анализатора.
• Используйте подсказки редактора для навигации по полям и проверки корректности структуры.
• Если доступ к $schema ограничен корпоративной политикой, обычно помогает публикация схем на внутреннем артефакт-сервере (intranet) или установка схем локально с сопоставлением в настройках VS Code (параметр json.schemas). Также вы можете изменить ссылку на тот же файл в дистрибутиве анализатора.

JSON схемы структурированных логов утилит из дистрибутива PVS-Studio

Ссылки на эти файлы вписываются в поле $schema каждого структурированного лога. Если по какой-то причине вы не можете получить к ним доступ локально, то можете воспользоваться ссылками ниже:

• pvs-studio-analyzer V1;
• pvs-studio-analyzer V2;
• pvs-studio-cmd V1;
• pvs-studio V1;
• pvs-studio V2;
• pvs-studio-dotnet V1.

Приватность и требования безопасности

Диагностические логи могут содержать информацию, которая относится к конфиденциальной:

• пути к исходникам и артефактам сборки;
• параметры компиляции/препроцессирования;
• переменные окружения;
• части вывода сторонних инструментов.

Если для вас критична передача такой информации, то рекомендуем использовать --logging-options skip-sensitive (минимизирует и частично маскирует чувствительные данные в логах), а также:

• перед передачей логов выполнить внутреннюю проверку (поиск токенов/секретов/URL/имен проектов);
• при необходимости согласовать канал передачи с политикой безопасности организации.

Что отправлять в техническую поддержку

Рекомендуемый комплект:

• структурированный лог (*.json), указанный в --enable-logging;
• дополнительно для С/С++ анализатора:
  • препроцессированные файлы (*.PVS-Studio.i), относящиеся к проблемному файлу (появятся после указания опции --dump-intermediate-files);
  • файлы конфигурации запуска (*.PVS-Studio.cfg), относящиеся к проблемному файлу (появятся после указания опции --dump-intermediate-files);
  • файлы stacktrace (*.PVS-Studio.stacktrace.txt);
  • любые дополнительные файлы для уточнения проблемы (заголовочные файлы, файлы исходного кода).

FAQ

Где находятся логи?

Структурированный лог анализатора

Сохраняется точно по пути, который вы указали в --enable-logging.

Структурированный лог исполнителей

Не создаётся, встраивается в структурированный лог анализатора при указании опции embed-runs.

Сырой лог анализатора

Сохраняется в той же директории, что файл из --enable-logging, но с суффиксом *-raw.PVS-Studio.log.

Сырой лог исполнителя

Сырые логи исполнителей сохраняются рядом с анализируемыми исходными файлами. Их общий признак — имя файла заканчивается на *-raw.PVS-Studio.log.

Как найти все сырые логи в проекте

Linux/macOS (bash):

find <папка_проекта> -name '*-raw.PVS-Studio.log'

Windows PowerShell:

Get-ChildItem -Path <папка_проекта> -Recurse -Filter "*-raw.PVS-Studio.log"

Можно ли посмотреть содержимое лог-файлов?

Да, все файлы являются текстовыми. Вы можете открыть любой из них и посмотреть содержимое.

Я не вижу структурированный JSON-лог. Что делать?

Найдите сырой лог анализатора рядом с путём --enable-logging.

Запустите конвертацию вручную:

pvs-diag-collector convert --input <путь_к_сырому_логу> --output ./pvs-diag.json

Если конвертация не удаётся — отправьте сырой лог в поддержку.

Почему сырые логи остались после анализа?

По умолчанию временные файлы и сырые логи удаляются по завершении анализа. Сырые логи сохраняются (не удаляются), если выполняется хотя бы одно из условий:

• включена опция --logging-options dump-intermediate-files;
• анализатор аварийно завершил работу.

Практическое следствие: даже при падении у вас, как правило, остаются сырые логи, которые можно сконвертировать или отправить в поддержку в исходном виде.

Можно ли использовать лог в автоматизации (CI/скрипты)?

Да. Структурированный лог — валидный JSON, пригодный для парсинга.

Если нужно интегрировать конвертацию в пайплайн, используйте pvs-diag-collector convert и проверяйте код возврата (0/1).

Как удобнее всего изучать лог?

Откройте JSON в VS Code: наличие $schema позволяет видеть подсказки по полям и допустимым значениям. Это ускоряет навигацию и снижает риск ошибок при интерпретации.

Была ли полезна эта страница документации?

Ваше сообщение отправлено

Мы ответим вам на:

Если вы так и не получили ответ, пожалуйста, проверьте, отфильтровано ли письмо в одну из следующих стандартных папок:

• Промоакции
• Оповещения
• Спам

Напишите, пожалуйста, на какой вопрос вы не смогли найти ответ, и наши разработчики ответят вам лично по почте.

Даю согласие на обработку своих персональных данных в соответствии с Политикой обработки персональных данных