# Registro e diagnósticos

QV2QS 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 |

Nota informativa

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 |

## Saiba mais

* [Referência de argumentos](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [Solução de problemas com o](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/troubleshooting/index.htm)