# Журналирование и диагностика

QV2QS записывает структурированные журналы диагностики при каждом запуске. Система логирования имеет два уровня: постоянный системный журнал, сохраняющийся между запусками, и структурированный журнал для каждого запуска, поставляемый вместе с выходными данными конвертации.

## Системный журнал

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

Местоположение: `%LOCALAPPDATA%\QV2QS\qv2qs.log`

Системный журнал использует обработчик файлов с ротацией со следующими настройками.

| Параметр | Значение |
| --- | --- |
| Максимальный размер файла | 25 МБ |
| Сохраняемые файлы резервных копий | 3 |
| Шаблон файла | `qv2qs.log`, `qv2qs.log.1`, `qv2qs.log.2`, `qv2qs.log.3` |

Когда активный файл журнала достигает 25 МБ, QV2QS выполняет ротацию файла и создает новый файл журнала. Сохраняются три последние резервные копии. Более старые резервные копии удаляются автоматически.

## Структурированный журнал для каждого запуска

Каждый запуск преобразования создает отдельный файл журнала, содержащий подробные сведения о событиях этого запуска. Файл называется `qv2qs_run_<version>_<timestamp>.log` и записан в формате значений, разделенных табуляцией (TSV), со столбцом данных JSON.

Местоположение по умолчанию: `%LOCALAPPDATA%\QV2QS\logs\`

В режиме одного проекта QV2QS перемещает файл журнала в подпапку `logs/` выходной папки проекта (например, `<outputDir>/Sales/logs/`) после инициализации выходной папки. Файл журнала включен в результаты конвертации.

В пакетном режиме журналы отдельных проектов записываются в подпапку `logs/` в выходной папке каждого проекта.

### Формат файла журнала

Каждый файл журнала начинается со строки заголовка TSV:

```
ts_utc	level	version	run_id	logger	event	message	data
```

| Столбец | Описание |
| --- | --- |
| `ts_utc` | Метка времени ISO 8601 в UTC, миллисекундная Πрецизионность |
| `level` | Уровень логирования: `DEBUG`, `INFO`, `WARNING`, `ERROR` или `CRITICAL` |
| `version` | Версия QV2QS |
| `run_id` | Уникальный идентификатор запуска в формате `YYYYMMDD-HHMMSS-<hex>` |
| `logger` | Имя логгера (обычно `qv2qs`) |
| `event` | Строка типа события (например, `startup`, `conversion_complete`, `batch_local_complete`) |
| `message` | Понятное человеку описание |
| `data` | JSON-объект с контекстными парами «ключ-значение» |

### Коллизии меток времени

Если два запуска начинаются в течение одной секунды и для них формируется одинаковая Метка времени, QV2QS добавляет `_2`, `_3` или последующие номера к имени файла во избежание перезаписи.

## Какой журнал проверить

QV2QS записывает данные в два отдельных журнала на разных этапах выполнения. Системный журнал всегда доступен. Журнал отдельного запуска создается только после завершения инициализации при запуске.

| Сценарий | Журнал для проверки в первую очередь | Почему |
| --- | --- | --- |
| Процесс аварийно завершает работу или сразу же завершается | Системный журнал | Журнал отдельного запуска еще не создан |
| Генерация PRJ завершается сбоем до начала конвертации | Системный журнал | События PRJ записываются в журнал до инициализации выходного каталога |
| При пакетном запуске отображаются файлы с ошибками без подробностей | Системный журнал | Ошибки уровня пакета (отсутствие QlikView Desktop, сбои предварительных условий) регистрируются в системном журнале |
| Преобразование приводит к неожиданному результату | Журнал каждого запуска в выходном каталоге | Решения о преобразовании на уровне объектов и предупреждения записываются в журнал каждого запуска |
| Облачное развертывание завершается сбоем | Журнал каждого запуска в выходном каталоге | Вызовы API, ошибки аутентификации и ход загрузки записываются в журнал каждого запуска |

Примечание к информации

Системный журнал и журнал отдельного запуска регистрируют одни и те же события в течение периода перекрытия, когда оба активны. Ведение системного журнала начинается при запуске процесса. Журнал отдельного запуска начинается после разбора аргументов командной строки и создания выходного каталога. Если сбой происходит до создания журнала отдельного запуска, только системный журнал содержит диагностическую информацию.

## Уровни логирования

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

| Уровень | Описание |
| --- | --- |
| `DEBUG` | Подробная диагностическая информация для поиска и устранения неполадок |
| `INFO` | Общие операционные сообщения (по умолчанию) |
| `WARNING` | Непредвиденные условия, не препятствующие преобразованию |
| `ERROR` | Сбои, влияющие на отдельные объекты или операции |
| `CRITICAL` | Критические сбои, останавливающие выполнение |

Установите уровень ведения журнала с помощью `--logLevel` или переменной среды `QV2QS_LOG_LEVEL`. Флаг CLI имеет приоритет, если заданы оба.

Установите `--logLevel DEBUG`, чтобы получать наиболее подробные выходные данные. Записи уровня отладки включают решения по преобразованию, вызовы API облака, изменения скриптов и детали обработки объектов.

Чтобы включить ведение журнала отладки без изменения командной строки, установите переменную среды перед запуском QV2QS:

```
set QV2QS_LOG_LEVEL=DEBUG
QV2QS.exe --prjPath ./MyApp-prj --outputDir ./output --qvw MyApp.qvw --unbuildOnly
```

## Очистка журналов

Файлы журналов накапливаются между запусками в постоянном каталоге журналов. Используйте `--cleanLogs`, чтобы удалять файлы журналов старше 30 дней в начале запуска. Очистка применяется только к постоянному каталогу журналов; журналы отдельных проектов в выходных каталогах не затрагиваются.

## Маскирование секретов

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

## Журналирование движка QlikView Desktop

Когда включена генерация PRJ, QV2QS записывает в журнал, какой движок QlikView Desktop используется для каждого файла. Событие журнала `prj_generate_start` регистрирует, активный ли встроенный портативный движок или установленная в системе версия, и включает версию файла встроенного исполняемого файла, если она доступна.

После установки подключения к QlikView Desktop событие `prj_qv_ready` регистрирует версию QlikView, сообщаемую запущенным движком (например, `12.100.20100.0`). При использовании встроенного движка в поле `exe_file_version` записывается версия файла, считанная из исполняемого файла.

В пакетном режиме событие журнала `prj_batch_prereq` регистрирует выбор движка и версию комплекта для всего пакета до обработки каких-либо файлов. Если недоступны ни встроенный движок, ни системная установка, ошибка регистрируется в системном журнале как `prj_batch_no_qv`.

Установите `--logLevel DEBUG`, чтобы записывать подробные шаги разрешения движка, включая пути к файлам, проверяемые при обнаружении движка.

## Вывод в консоль против логирования в файл

Вывод в консоль и логирование в файл являются независимыми системами.

| Аспект | Консоль | Журнал файла |
| --- | --- | --- |
| Формат | Форматированный текст с опциональными цветами и спиннерами | Структурированный TSV с данными JSON |
| Управляется | `--console pretty\\|plain\\|silent\\|ui` | `--logLevel`, `--logDir` |
| Содержимое | Ход выполнения и результаты для пользователя | Полные диагностические события |
| Маскирование секретов | Не применимо | Применяется автоматически |

Вывод консоли не отображается в файлах журналов. Флаг `--console silent` подавляет вывод в консоль, не влияя на ведение журнала в файле.

## Аргументы CLI

| Аргумент | Описание | По умолчанию |
| --- | --- | --- |
| `--logLevel LEVEL` | Уровень детализации журнала: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | `INFO` |
| `--logDir FOLDER` | Переопределить папку вывода журналов для каждого запуска. Относительные пути разрешаются относительно текущего рабочего каталога, а не выходного каталога. Не влияет на постоянный системный журнал в `%LOCALAPPDATA%`. | `%LOCALAPPDATA%\QV2QS\logs\` (для одного проекта) или `<outputDir>/logs/` (пакетный режим) |
| `--cleanLogs` | Удалять файлы журналов старше 30 дней перед запуском | Выкл. |

## Подробнее

* [Справочник аргументов](https://help.qlik.com/ru-RU/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [Поиск и устранение неисправностей](https://help.qlik.com/ru-RU/migration/Content/Qv2qsMigration/troubleshooting/index.htm)