Журналирование и диагностика
Последнее обновление: 14.10.2026QV2QS записывает структурированные журналы диагностики при каждом запуске. Система логирования имеет два уровня: постоянный системный журнал, сохраняющийся между запусками, и структурированный журнал для каждого запуска, поставляемый вместе с выходными данными конвертации.
Системный журнал
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 дней перед запуском | Выкл. |