# Диагностика работы анализатора PVS\-Studio > На текущий момент доступно только для утилит \`pvs\-studio\-analyzer\` и \`PVS\-Studio\_Cmd\`\\\. Диагностическое логирование предназначено для быстрого сбора воспроизводимой информации о запуске анализатора: фактические параметры, окружение, результат выполнения, а также сведения о том, какие файлы были проанализированы или пропущены\. Результат сохраняется в виде структурированного лога \(JSON\), который удобен для чтения, автоматической обработки и передачи в техническую поддержку\. Если вы столкнулись с проблемами в работе анализатора \(падениями, некорректными завершениями работы и прочими ситуациями, которые мешают вам использовать PVS\-Studio\), то при обращении в техническую поддержку стоит прикрепить полученные логи\. Обратиться в техническую поддержку можно через [форму на сайте](https://pvs-studio.ru/ru/about-feedback/)\. ## Термины \(используются далее по тексту\) **Структурированный лог** — текстовый файл, содержащий диагностическую информацию в формате JSON\. Пригоден для машинной обработки\. **Сырой лог** — текстовый файл с промежуточной информацией, из которого формируется структурированный лог\. Имеет суффикс `*-raw.PVS-Studio.log`\. Не предназначен для использования при самостоятельной диагностике проблем\. **Анализатор \(frontend\)** — `pvs-studio-analyzer` \(`CompileCommandsAnalyzer`\) и `PVS-Studio_Cmd`; **Исполнитель** \(анализа; запускается анализатором\) — `pvs-studio`\. ## Когда использовать Рекомендуется включать диагностическое логирование, если: * анализ завершился с ошибкой \(ненулевой код возврата\) или аварийно; * настройки анализа "не применились" или применились не так, как ожидалось; * ожидаемые файлы не попали в анализ; * нужно подтвердить, какая конфигурация фактически использовалась \(для аудита/сертификации/разбора инцидента\); * требуется детальная информация для обращения в поддержку\. ## Быстрый старт 1\) Запуск анализа с формированием структурированного лога: ```cpp # Для 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\) Если структурированный лог не сформировался \(из\-за какой\-либо ошибки\), то конвертацию можно запустить вручную: ```cpp pvs-diag-collector convert --input ./pvs-diag-raw.PVS-Studio.log \ --output ./pvs-diag.json ``` ### Как это работает 1. Вы запускаете анализатор со включённым логированием; 1. Во время работы диагностические данные записываются в сырые логи; 1. По завершении анализа формируется структурированный JSON\-лог; 1. Если на этапе формирования JSON что\-то пошло не так, то сырые логи остаются на диске\. Их можно [сконвертировать вручную с помощью утилиты `pvs-diag-collector`](https://pvs-studio.ru/ru/docs/manual/7185/#how_to_manual) или отправить в поддержку\. ## Включение логирования и его опции `--enable-logging ` — обязательный флаг для включения логирования и сохранения структурированного JSON\-лога в указанный файл\. **Опции логирования** Опции задаются флагом `--logging-options `\. Значения передаются через запятую, без пробелов\. Корректно: ```cpp --logging-options skip-sensitive,dump-intermediate-files ``` Некорректно: ```cpp --logging-options skip-sensitive, dump-intermediate-files ``` Доступные опции: |N п/п|Опция|Описание| |---|---|---| |1|\`skip\-sensitive\`|Минимизирует и частично маскирует чувствительные данные в логах \\\(например, значения переменных окружения и некоторые артефакты — в зависимости от сценария анализа\\\)| |2|\`dump\-intermediate\-files\`|Сохраняет промежуточные файлы после анализа \\\(например, препроцессированные \`\.i\` и конфигурационные \`\.cfg\` файлы, а также сырые логи\\\)| |3|\`embed\-runs\`|Добавляет в структурированный лог расширенную информацию о выполненных запусках исполнителей \\\(если они доступны в собранных данных\\\)| Примеры: ```cpp # Для 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`\) в структурированный\. > При обычном сценарии работы эти действия выполняются анализатором автоматически\\\. **Использование** ```cpp pvs-diag-collector.exe convert [FILE] [-i ] [-o ] [--embed-runs] [-j ] ``` **Опции утилиты** |N п/п|Опция|Описание| |---|---|---| |1|\`\-i\`, \`\-\-input\`|Путь до входного сырого лога\\\.| |2|\`\-o\`, \`\-\-output\`|Путь до выходного структурированного лога\\\. Если опция не указана, то результат выводится в \`stdout\`\\\.| |3|\`\-\-embed\-runs\`|Добавляет в структурированный лог расширенную информацию о выполненных запусках исполнителей \\\(если они доступны в собранных данных\\\)\\\.| |4| \`\-j\`, \`\-\-threads\`|Количество потоков \\\(по умолчанию 1\\\)\\\. При использовании без аргументов или со значением \`0\` — установит количество потоков автоматически\\\.| **Примеры** ```cpp # Вывод в файл с подробными сведениями о запусках исполнителей 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 \(см\. раздел про [просмотр в редакторе](https://pvs-studio.ru/ru/docs/manual/7185/#json_log_ease_of_use)\)\. ### Основные разделы Обычно полезно начать с: * `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, он будет: * показывать описания полей при наведении; * подсказывать допустимые значения; * подсвечивать ошибки типов и структуры\. **Рекомендуемый сценарий** 1. Откройте JSON\-лог в редакторе кода \(например, Microsoft Visual Studio Code\)\. 1. Убедитесь, что значение `$schema` доступно \(в корпоративной сети/интернете — согласно вашей политике\)\. Если файл по указанной ссылке недоступен, то вы можете изменить ссылку на тот же файл в дистрибутиве анализатора\. 1. Используйте подсказки редактора для навигации по полям и проверки корректности структуры\. 1. Если доступ к `$schema` ограничен корпоративной политикой, обычно помогает публикация схем на внутреннем артефакт\-сервере \(intranet\) или установка схем локально с сопоставлением в настройках VS Code \(параметр `json.schemas`\)\. Также вы можете изменить ссылку на тот же файл в дистрибутиве анализатора\. ### JSON схемы структурированных логов утилит из дистрибутива PVS\-Studio Ссылки на эти файлы вписываются в поле `$schema` каждого структурированного лога\. Если по какой\-то причине вы не можете получить к ним доступ локально, то можете воспользоваться ссылками ниже: * [pvs\-studio\-analyzer V1](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio-analyzer_v1.schema.json); * [pvs\-studio\-analyzer V2](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio-analyzer_v2.schema.json); * [pvs\-studio\-cmd V1](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio-cmd_v1.schema.json); * [pvs\-studio V1](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio_v1.schema.json); * [pvs\-studio V2](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio_v2.schema.json); * [pvs\-studio\-dotnet V1](https://files.pvs-studio.ru/media/logging-system/log_pvs-studio-dotnet_v1.schema.json)\. ## Приватность и требования безопасности Диагностические логи могут содержать информацию, которая относится к конфиденциальной: * пути к исходникам и артефактам сборки; * параметры компиляции/препроцессирования; * переменные окружения; * части вывода сторонних инструментов\. Если для вас критична передача такой информации, то рекомендуем использовать `--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\): ```cpp find <папка_проекта> -name '*-raw.PVS-Studio.log' ``` Windows PowerShell: ```cpp Get-ChildItem -Path <папка_проекта> -Recurse -Filter "*-raw.PVS-Studio.log" ``` ### Можно ли посмотреть содержимое лог\-файлов? Да, все файлы являются текстовыми\. Вы можете открыть любой из них и посмотреть содержимое\. ### Я не вижу структурированный JSON\-лог\. Что делать? Найдите сырой лог анализатора рядом с путём `--enable-logging`\. Запустите конвертацию вручную: ```cpp pvs-diag-collector convert --input <путь_к_сырому_логу> --output ./pvs-diag.json ``` Если конвертация не удаётся — отправьте сырой лог в поддержку\. ### Почему сырые логи остались после анализа? По умолчанию временные файлы и сырые логи удаляются по завершении анализа\. Сырые логи сохраняются \(не удаляются\), если выполняется хотя бы одно из условий: * включена опция `--logging-options dump-intermediate-files`; * анализатор аварийно завершил работу\. Практическое следствие: даже при падении у вас, как правило, остаются сырые логи, которые можно сконвертировать или [отправить в поддержку](https://pvs-studio.ru/ru/about-feedback/) в исходном виде\. ### Можно ли использовать лог в автоматизации \(CI/скрипты\)? Да\. Структурированный лог — валидный JSON, пригодный для парсинга\. Если нужно интегрировать конвертацию в пайплайн, используйте `pvs-diag-collector convert` и проверяйте код возврата \(0/1\)\. ### Как удобнее всего изучать лог? Откройте JSON в VS Code: наличие `$schema` позволяет видеть подсказки по полям и допустимым значениям\. Это ускоряет навигацию и снижает риск ошибок при интерпретации\.