Registro e diagnósticos
Última atualização: 14/10/2026QV2QS escreve logs de diagnóstico estruturados a cada execução. O sistema de log tem dois níveis: um log de sistema persistente que sobrevive entre execuções, e um log estruturado por execução que acompanha a saída da conversão.
Log do sistema
QV2QS mantém um arquivo de log rotativo em uma localização fixa em disco. O log do sistema começa quando o executável é iniciado e registra eventos de nível de aplicação independentemente de qualquer projeto ou lote.
Localização: %LOCALAPPDATA%\QV2QS\qv2qs.log
O log do sistema usa um manipulador de arquivo rotativo com as seguintes configurações.
| Configuração | Valor |
|---|---|
| Tamanho máximo do arquivo | 25 MB |
| Arquivos de backup mantidos | 3 |
| Padrão de arquivo | qv2qs.log, qv2qs.log.1, qv2qs.log.2, qv2qs.log.3 |
Quando o arquivo de log ativo atinge 25 MB, o QV2QS rotaciona o arquivo e cria um novo arquivo de log. Os três backups mais recentes são mantidos. Backups mais antigos são excluídos automaticamente.
Log estruturado por execução
Cada execução de conversão gera um arquivo de log separado contendo eventos detalhados dessa execução. O arquivo se chama qv2qs_run_<version>_<timestamp>.log e é gravado no formato de valores separados por tabulação (TSV) com uma coluna de dados JSON.
Localização padrão: %LOCALAPPDATA%\QV2QS\logs\
No modo de projeto único, o QV2QS promove o arquivo de log para a subpasta logs/ da pasta de saída do projeto (por exemplo, <outputDir>/Sales/logs/) após a pasta de saída ser inicializada. O arquivo de log está incluído na saída da conversão.
No modo em lote, os logs por projeto são gravados na subpasta logs/ dentro da pasta de saída de cada projeto.
Formato de arquivo de log
Cada arquivo de log começa com uma linha de cabeçalho TSV:
ts_utc level version run_id logger event message data
| Coluna | Descrição |
|---|---|
ts_utc
|
Carimbo de data/hora ISO 8601 em UTC com precisão de milissegundos |
level
|
Nível de log: DEBUG, INFO, WARNING, ERROR ou CRITICAL |
version
|
Versão do QV2QS |
run_id
|
Identificador exclusivo de execução no formato YYYYMMDD-HHMMSS-<hex> |
logger
|
Nome do logger (geralmente qv2qs) |
event
|
String do tipo de evento (por exemplo, startup, conversion_complete, batch_local_complete) |
message
|
Descrição legível por humanos |
data
|
Objeto JSON com pares chave-valor contextuais |
Colisões de carimbo de data/hora
Se duas execuções começarem dentro do mesmo segundo e produzirem o mesmo carimbo de data/hora, o QV2QS adiciona _2, _3 ou números subsequentes ao nome do arquivo para evitar a substituição.
Qual log verificar
O QV2QS grava em dois logs separados em diferentes etapas de uma execução. O log do sistema está sempre disponível. O log por execução só é criado após a conclusão da inicialização.
| Cenário | Log a ser verificado primeiro | Por quê |
|---|---|---|
| O processo falha ou é encerrado imediatamente | Log do sistema | O log por execução ainda não foi criado |
| A geração do PRJ falha antes do início da conversão | Log do sistema | Os eventos PRJ são registrados antes que o diretório de saída seja inicializado |
| Uma execução em lote exibe arquivos com falha sem detalhes | Log do sistema | Erros em nível de lote (QlikView Desktop ausente, falhas de pré-requisitos) são registrados no log do sistema |
| A conversão gera uma saída inesperada | Log por execução no diretório de saída | As decisões de conversão e os avisos em nível de objeto são registrados no log por execução |
| A implementação na nuvem falha | Log por execução no diretório de saída | As chamadas de API, os erros de autenticação e o progresso do upload são registrados no log por execução |
O log do sistema e o log por execução registram os mesmos eventos durante o período de sobreposição quando ambos estão ativos. O log do sistema começa na inicialização do processo. O log por execução começa depois que os argumentos de linha de comando são analisados e o diretório de saída é criado. Se ocorrer uma falha antes que o log por execução seja criado, apenas o log do sistema conterá informações de diagnóstico.
Níveis de log
Cinco níveis de log estão disponíveis, listados do mais para o menos detalhado.
| Nível | Descrição |
|---|---|
DEBUG
|
Informações detalhadas de diagnóstico para solução de problemas |
INFO
|
Mensagens operacionais gerais (padrão) |
WARNING
|
Condições inesperadas que não impedem a conversão |
ERROR
|
Falhas que afetam objetos ou operações individuais |
CRITICAL
|
Falhas graves que interrompem a execução |
Defina o nível de log com --logLevel ou a variável de ambiente QV2QS_LOG_LEVEL. A flag da CLI tem precedência quando ambos estiverem definidos.
Defina --logLevel DEBUG para capturar a saída mais detalhada. Entradas de nível de depuração incluem decisões de conversão, chamadas de API da nuvem, modificações de script e detalhes de processamento de objetos.
Para habilitar o log de depuração sem modificar a linha de comando, defina a variável de ambiente antes de executar o QV2QS:
set QV2QS_LOG_LEVEL=DEBUG
QV2QS.exe --prjPath ./MyApp-prj --outputDir ./output --qvw MyApp.qvw --unbuildOnly
Limpeza de logs
Os arquivos de log se acumulam entre as execuções no diretório de logs persistente. Use --cleanLogs para excluir arquivos de log com mais de 30 dias no início de uma execução. A limpeza se aplica apenas ao diretório de logs persistentes; os logs por projeto nos diretórios de saída não são afetados.
Mascaramento de segredos
As entradas de log mascaram automaticamente valores sensíveis. Chaves de API, tokens, senhas e segredos do cliente são ocultados para exibir apenas os últimos quatro caracteres. Argumentos de linha de comando que contêm segredos também são mascarados quando registrados.
Registro em log do mecanismo do QlikView Desktop
Quando a geração de PRJ está habilitada, o QV2QS registra qual mecanismo do QlikView Desktop é usado para cada arquivo. O evento de log prj_generate_start registra se o mecanismo portátil integrado ou uma versão instalada no sistema está ativo e inclui a versão do arquivo do executável integrado quando disponível.
Após a conexão com o QlikView Desktop ser estabelecida, o evento prj_qv_ready registra a versão do QlikView relatada pelo mecanismo em execução (por exemplo, 12.100.20100.0). Quando o mecanismo integrado é usado, o campo exe_file_version registra a versão do arquivo lida do executável.
No modo em lote, o evento de log prj_batch_prereq registra a seleção do mecanismo e a versão empacotada para todo o lote antes que qualquer arquivo seja processado. Se nem um mecanismo integrado nem uma instalação do sistema estiverem disponíveis, o erro é registrado como prj_batch_no_qv no log do sistema.
Defina --logLevel DEBUG para capturar etapas detalhadas da resolução do mecanismo, incluindo os caminhos de arquivo verificados durante a descoberta do mecanismo.
Saída do console vs. registro em arquivo
A saída do console e o registro em arquivo são sistemas independentes.
| Aspecto | Console | Log do arquivo |
|---|---|---|
| Formato | Texto formatado com cores e spinners opcionais | TSV estruturado com dados JSON |
| Controlado por | --console pretty\|plain\|silent\|ui
|
--logLevel, --logDir |
| Conteúdo | Progresso e resultados voltados para o usuário | Eventos de diagnóstico completos |
| Mascaramento de segredos | Não aplicável | Aplicado automaticamente |
A saída do console não aparece nos arquivos de log. A flag --console silent suprime a saída do console sem afetar o registro em arquivo.
Argumentos da CLI
| Argumento | Descrição | Padrão |
|---|---|---|
--logLevel LEVEL
|
Verbosidade do log: DEBUG, INFO, WARNING, ERROR, CRITICAL |
INFO
|
--logDir FOLDER
|
Substitua a pasta de saída de logs por execução. Os caminhos relativos são resolvidos a partir do diretório de trabalho atual, não do diretório de saída. Não afeta o log persistente do sistema em %LOCALAPPDATA%. |
%LOCALAPPDATA%\QV2QS\logs\ (projeto único) ou <outputDir>/logs/ (em lote) |
--cleanLogs
|
Excluir arquivos de log com mais de 30 dias antes da execução | Desativado |