# Registrazione e diagnostica

QV2QS scrive log diagnostici strutturati durante ogni esecuzione. Il sistema di logging ha due livelli: un log di sistema persistente che sopravvive tra le esecuzioni, e un log strutturato per esecuzione che viene fornito con l'output di conversione.

## Registro di sistema

QV2QS mantiene un file di log a rotazione in una posizione fissa sul disco. Il log di sistema si avvia quando l'eseguibile viene avviato e registra eventi a livello di applicazione indipendentemente da qualsiasi progetto o batch.

Posizione: `%LOCALAPPDATA%\QV2QS\qv2qs.log`

Il log di sistema utilizza un gestore di file a rotazione con le seguenti impostazioni.

| Impostazione | Valore |
| --- | --- |
| Dimensione massima del file | 25 MB |
| File di backup conservati | 3 |
| Modello file | `qv2qs.log`, `qv2qs.log.1`, `qv2qs.log.2`, `qv2qs.log.3` |

Quando il file di log attivo raggiunge i 25 MB, QV2QS ruota il file e crea un nuovo file di log. I tre backup più recenti vengono conservati. I backup meno recenti vengono eliminati automaticamente.

## Log strutturato per esecuzione

Ogni esecuzione di conversione produce un file di log separato contenente eventi dettagliati per tale esecuzione. Il file è denominato `qv2qs_run_<version>_<timestamp>.log` ed è scritto in formato valori separati da tabulazione (TSV) con una colonna di dati JSON.

Posizione predefinita: `%LOCALAPPDATA%\QV2QS\logs\`

In modalità progetto singolo, QV2QS promuove il file di log nella `logs/` sottocartella della cartella di output del progetto (ad esempio, `<outputDir>/Sales/logs/`) dopo l'inizializzazione della cartella di output. Il file di log è incluso nell'output della conversione.

In modalità batch, i log per progetto vengono scritti nella sottocartella `logs/` all'interno di ogni cartella di output del progetto.

### Formato file di log

Ogni file di log inizia con una riga di intestazione TSV:

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

| Colonna | Descrizione |
| --- | --- |
| `ts_utc` | timestamp ISO 8601 in UTC con precisione al millisecondo |
| `level` | Livello di log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, o `CRITICAL` |
| `version` | QV2QS versione |
| `run_id` | Identificatore univoco dell'esecuzione nel formato `YYYYMMDD-HHMMSS-<hex>` |
| `logger` | Nome del logger (tipicamente `qv2qs`) |
| `event` | Stringa tipo evento (ad esempio, `startup`, `conversion_complete`, `batch_local_complete`) |
| `message` | Descrizione leggibile dall'utente |
| `data` | Oggetto JSON con coppie chiave-valore contestuali |

### Collisioni di Timestamp

Se due esecuzioni iniziano nello stesso secondo e producono lo stesso timestamp, QV2QS aggiunge `_2`, `_3`, o numeri successivi al nome del file per evitare la sovrascrittura.

## Quale log controllare

QV2QS scrive su due log separati in diverse fasi di un'esecuzione. Il log di sistema è sempre disponibile. Il log per esecuzione viene creato solo dopo il completamento dell'inizializzazione all'avvio.

| Scenario | Log da controllare prima | Perché |
| --- | --- | --- |
| Il processo si arresta in modo anomalo o termina immediatamente | Log di sistema | Il log per esecuzione non è ancora stato creato |
| La generazione PRJ fallisce prima dell'inizio della conversione | Log di sistema | Gli eventi PRJ vengono registrati prima che la directory di output venga inizializzata |
| Un'esecuzione batch mostra file non riusciti senza dettagli | Log di sistema | Errori a livello di batch (QlikView Desktop mancante, errori di prerequisito) vengono registrati nel registro di sistema |
| Conversione produce output imprevisto | Log per esecuzione nella directory di output | Le decisioni e gli avvisi di conversione a livello di oggetto vengono registrati nel log di ogni esecuzione |
| Distribuzione cloud non riuscita | Log per esecuzione nella directory di output | Le chiamate API, gli errori di autenticazione e l'avanzamento del caricamento vengono registrati nel log per esecuzione |

Nota informatica

Il log di sistema e il log per esecuzione registrano gli stessi eventi durante il periodo di sovrapposizione quando entrambi sono attivi. Il log di sistema inizia all'avvio del processo. Il log per esecuzione inizia dopo che gli argomenti della riga di comando sono stati analizzati e la directory di output è stata creata. Se si verifica un guasto prima della creazione del log per esecuzione, solo il log di sistema contiene informazioni diagnostiche.

## Livelli di log

Cinque livelli di log sono disponibili, elencati dal più al meno dettagliato.

| Livello | Descrizione |
| --- | --- |
| `DEBUG` | Informazioni diagnostiche dettagliate per la risoluzione dei problemi |
| `INFO` | Messaggi operativi generali (predefinito) |
| `WARNING` | Condizioni impreviste che non impediscono la conversione |
| `ERROR` | Guasti che interessano singoli oggetti o operazioni |
| `CRITICAL` | Guasti gravi che arrestano l'esecuzione |

Imposta il livello di log con `--logLevel` o la `QV2QS_LOG_LEVEL` variabile d'ambiente. Il flag CLI ha la precedenza quando entrambi sono impostati.

Imposta `--logLevel DEBUG` per acquisire l'output più dettagliato. Voci a livello di debug includono decisioni di conversione, chiamate API cloud, modifiche agli script e dettagli sull'elaborazione degli oggetti.

Per abilitare la registrazione di debug senza modificare la riga di comando, impostare la variabile di ambiente prima di eseguire QV2QS:

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

## Pulizia dei log

I file di log si accumulano tra le esecuzioni nella directory di log persistente. Utilizza `--cleanLogs` per eliminare i file di log più vecchi di 30 giorni all'avvio di un'esecuzione. La pulizia si applica solo alla directory dei log persistenti; i log per progetto nelle directory di output non sono interessati.

## Mascheramento segreto

Le voci di log mascherano automaticamente i valori sensibili. Le chiavi API, i token, le password e i segreti client vengono oscurati per mostrare solo gli ultimi quattro caratteri. Anche gli argomenti della riga di comando contenenti segreti vengono mascherati quando registrati.

## Registrazione del motore QlikView Desktop

Quando la generazione PRJ è abilitata, QV2QS registra quale motore QlikView Desktop viene utilizzato per ogni file. L'evento di log `prj_generate_start` registra se il motore portatile in bundle o una versione installata nel sistema è attivo e include la versione del file dell'eseguibile in bundle, quando disponibile.

Una volta stabilita la connessione a QlikView Desktop, l'evento `prj_qv_ready` registra la versione di QlikView riportata dal motore in esecuzione (ad esempio, `12.100.20100.0`). Quando viene utilizzato il motore in bundle, il campo `exe_file_version` registra la versione del file letta dall'eseguibile.

In modalità batch, l'evento di log `prj_batch_prereq` registra la selezione del motore e la versione in bundle per l'intero batch prima che vengano elaborati i file. Se non è disponibile né un motore in bundle né un'installazione di sistema, l'errore viene registrato come `prj_batch_no_qv` nel registro di sistema.

Imposta `--logLevel DEBUG` per acquisire i passaggi dettagliati di risoluzione del motore, inclusi i percorsi dei file controllati durante il rilevamento del motore.

## Output della console vs. registrazione su file

L'output della console e la registrazione su file sono sistemi indipendenti.

| Aspetto | Console | File di log |
| --- | --- | --- |
| Formato | Testo formattato con colori opzionali e spinner | Strutturato TSV con dati JSON |
| Controllato da | `--console pretty\\|plain\\|silent\\|ui` | `--logLevel`, `--logDir` |
| Contenuto | Progresso e risultati rivolti all'utente | Completi eventi diagnostici |
| Mascheramento segreto | Non applicabile | Applicato automaticamente |

L'output della console non appare nei file di log. Il `--console silent` flag elimina l'output della console senza influire sulla registrazione dei file.

## Argomenti CLI

| Argomento | Descrizione | Predefinito |
| --- | --- | --- |
| `--logLevel LEVEL` | Verbosità del log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | `INFO` |
| `--logDir FOLDER` | Sovrascrivi la cartella di output dei log specifica per esecuzione. I percorsi relativi vengono risolti dalla directory di lavoro corrente, non dalla directory di output. Non influisce sul log di sistema persistente in `%LOCALAPPDATA%`. | `%LOCALAPPDATA%\QV2QS\logs\` (progetto singolo) o `<outputDir>/logs/` (lotto) |
| `--cleanLogs` | Elimina i file di log più vecchi di 30 giorni prima dell'esecuzione | Disattivato |

## Scopri di più

* [Riferimento argomento](https://help.qlik.com/it-IT/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [Risoluzione dei problemi](https://help.qlik.com/it-IT/migration/Content/Qv2qsMigration/troubleshooting/index.htm)