Journalisation et diagnostics
Dernière mise à jour : 14/10/2026QV2QS enregistre des journaux de diagnostic structurés lors de chaque exécution. Le système de journalisation comporte deux niveaux : un journal système persistant qui survit d'une exécution à l'autre, et un journal structuré par exécution qui est livré avec la sortie de conversion.
Journal système
QV2QS maintient un fichier journal tournant à un emplacement fixe sur le disque. Le journal système démarre lorsque l'exécutable se lance et enregistre les événements au niveau de l'application indépendamment de tout projet ou lot.
Emplacement : %LOCALAPPDATA%\QV2QS\qv2qs.log
Le journal système utilise un gestionnaire de fichiers rotatif avec les paramètres suivants.
| Paramètre | Valeur |
|---|---|
| Taille de fichier maximale | 25 Mo |
| Fichiers de sauvegarde conservés | 3 |
| Modèle de fichier | qv2qs.log, qv2qs.log.1, qv2qs.log.2, qv2qs.log.3 |
Lorsque le fichier journal actif atteint 25 Mo, QV2QS fait pivoter le fichier et crée un nouveau fichier journal. Les trois sauvegardes les plus récentes sont conservées. Les anciennes sauvegardes sont supprimées automatiquement.
Journal structuré par exécution
Chaque exécution de conversion produit un fichier journal distinct contenant les événements détaillés de cette exécution. Le fichier est nommé qv2qs_run_<version>_<timestamp>.log et est écrit au format valeurs séparées par des tabulations (TSV) avec une colonne de données JSON.
Emplacement par défaut : %LOCALAPPDATA%\QV2QS\logs\
En mode projet unique, QV2QS promeut le fichier journal dans le logs/ sous-dossier du dossier de sortie du projet (par exemple, <outputDir>/Sales/logs/) après l'initialisation du dossier de sortie. Le fichier journal est inclus dans la sortie de conversion.
En mode batch, les journaux par projet sont écrits dans le logs/ sous-dossier de chaque dossier de sortie de projet.
Format de fichier journal
Chaque fichier journal commence par une ligne d'en-tête TSV :
ts_utc level version run_id logger event message data
| Colonne | Description |
|---|---|
ts_utc
|
Horodatage ISO 8601 en UTC avec une précision en millisecondes |
level
|
Niveau de journalisation : DEBUG, INFO, WARNING, ERROR, ou CRITICAL |
version
|
QV2QS version |
run_id
|
Identifiant unique d'exécution au format YYYYMMDD-HHMMSS-<hex> |
logger
|
Nom de l'enregistreur (généralement qv2qs) |
event
|
Chaîne de type d'événement (par exemple, startup, conversion_complete, batch_local_complete) |
message
|
Description lisible par l'utilisateur |
data
|
Objet JSON avec des paires clé-valeur contextuelles |
Collisions d'horodatage
Si deux exécutions commencent dans la même seconde et produisent le même horodatage, QV2QS ajoute _2, _3, ou des numéros suivants au nom de fichier pour éviter l'écrasement.
Quel journal vérifier
QV2QS écrit dans deux fichiers journaux distincts à différentes étapes d'une exécution. Le journal système est toujours disponible. Le journal par exécution n'est créé qu'une fois l'initialisation au démarrage terminée.
| Scénario | Journal à vérifier en premier | Pourquoi |
|---|---|---|
| Le processus plante ou se ferme immédiatement | Journal système | Le journal par exécution n'a pas encore été créé |
| La génération PRJ échoue avant le début de la conversion | Journal système | Les événements PRJ sont enregistrés avant que le répertoire de sortie ne soit initialisé |
| Une exécution par lot affiche des fichiers en échec sans détails | Journal système | Les erreurs au niveau du lot (QlikView Desktop manquant, échecs de prérequis) sont enregistrées dans le journal système |
| La conversion génère une sortie inattendue | Journal par exécution dans le répertoire de sortie | Les décisions et avertissements de conversion au niveau de l'objet sont enregistrés dans le journal d'exécution |
| Le déploiement Cloud échoue | Journal par exécution dans le répertoire de sortie | Les appels API, les erreurs d'authentification et la progression du téléversement sont enregistrés dans le journal par exécution. |
Le journal système et le journal par exécution enregistrent les mêmes événements pendant la période de chevauchement lorsque les deux sont actifs. Le journal système commence dès le lancement du processus. Le journal par exécution commence après l'analyse des arguments de ligne de commande et la création du répertoire de sortie. Si une défaillance se produit avant la création du journal d'exécution, seul le journal système contient des informations de diagnostic.
Niveaux de journalisation
Cinq niveaux de journalisation sont disponibles, listés du plus au moins verbeux.
| Niveau | Description |
|---|---|
DEBUG
|
Informations de diagnostic détaillées pour la résolution des problèmes |
INFO
|
Messages opérationnels généraux (par défaut) |
WARNING
|
Conditions inattendues qui n'empêchent pas la conversion |
ERROR
|
Défaillances qui affectent des objets ou des opérations individuels |
CRITICAL
|
Pannes graves qui arrêtent l'exécution |
Définissez le niveau de journalisation avec --logLevel ou la QV2QS_LOG_LEVEL environnement variable. L'option CLI prend le pas lorsque les deux sont définis.
Définissez --logLevel DEBUG pour capturer la sortie la plus détaillée. Les entrées de niveau débogage incluent les décisions de conversion, les appels d'API cloud, les modifications de script et les détails de traitement d'objet.
Pour activer la journalisation de débogage sans modifier la ligne de commande, définissez la variable d'environnement avant d'exécuter QV2QS :
set QV2QS_LOG_LEVEL=DEBUG
QV2QS.exe --prjPath ./MyApp-prj --outputDir ./output --qvw MyApp.qvw --unbuildOnly
Nettoyage des journaux
Les fichiers journaux s'accumulent au fil des exécutions dans le répertoire de journaux persistant. Utilisez --cleanLogs pour supprimer les fichiers journaux de plus de 30 jours au début d'une exécution. Le nettoyage ne s'applique qu'au répertoire de journaux persistant ; les journaux par projet dans les répertoires de sortie ne sont pas affectés.
Masquage de secret
Les entrées de journal masquent automatiquement les valeurs sensibles. Les clés API, les jetons, les mots de passe et les secrets client sont masqués pour n'afficher que les quatre derniers caractères. Les arguments de ligne de commande contenant des secrets sont également masqués lorsqu'ils sont enregistrés.
Journalisation du moteur QlikView Desktop
Lorsque la génération PRJ est activée, QV2QS enregistre quel moteur QlikView Desktop est utilisé pour chaque fichier. L'événement de journal prj_generate_start enregistre si le moteur portable intégré ou une version installée sur le système est active et inclut la version du fichier de l'exécutable intégré lorsqu'elle est disponible.
Une fois la connexion à QlikView Desktop établie, l'événement prj_qv_ready enregistre la version de QlikView signalée par le moteur en cours d'exécution (par exemple, 12.100.20100.0). Lorsque le moteur intégré est utilisé, le champ exe_file_version enregistre la version du fichier lue à partir de l'exécutable.
En mode batch, l'événement de journalisation prj_batch_prereq enregistre la sélection du moteur et la version groupée pour l'ensemble du lot avant que tout fichier ne soit traité. Si ni un moteur intégré ni une installation système n'est disponible, l'erreur est consignée comme prj_batch_no_qv dans le journal système.
Configurer --logLevel DEBUG pour capturer les étapes détaillées de résolution du moteur, y compris les chemins de fichiers vérifiés lors de la découverte du moteur.
Sortie console vs. journalisation de fichier
La sortie console et la journalisation des fichiers sont des systèmes indépendants.
| Aspect | Console | Fichier journal |
|---|---|---|
| Format | Texte formaté avec couleurs et indicateurs de progression optionnels | TSV structuré avec données JSON |
| Contrôlé par | --console pretty\|plain\|silent\|ui
|
--logLevel, --logDir |
| Contenu | Progrès et résultats visibles pour l'utilisateur | Événements de diagnostic complets |
| Masquage de secret | Non applicable | Appliqué automatiquement |
Le résultat de la console n'apparaît pas dans les fichiers journaux. L'option --console silent supprime la sortie console sans affecter la journalisation des fichiers.
Arguments CLI
| Argument | Description | Par défaut |
|---|---|---|
--logLevel LEVEL
|
Niveau de verbosité des logs : DEBUG, INFO, WARNING, ERROR, CRITICAL |
INFO
|
--logDir FOLDER
|
Outrepasser le dossier de sortie des journaux par exécution. Les chemins relatifs sont résolus à partir du répertoire de travail actuel, et non à partir du répertoire de sortie. N'affecte pas le journal système persistant à %LOCALAPPDATA%. |
%LOCALAPPDATA%\QV2QS\logs\ (projet unique) ou <outputDir>/logs/ (lot) |
--cleanLogs
|
Supprimer les fichiers journaux datant de plus de 30 jours avant l'exécution | Désactivé |