Logging en diagnostiek
Laatst bijgewerkt: 14-10-2026QV2QS schrijft gestructureerde diagnostische logs bij elke run. Het logsysteem heeft twee niveaus: een persistent systeemlogboek dat behouden blijft over meerdere uitvoeringen heen, en een gestructureerd logboek per uitvoering dat wordt meegeleverd met de conversie-output.
Systeemlogboek
QV2QS onderhoudt een doorlopend logbestand op een vaste locatie op schijf. Het systeemlogboek begint wanneer het uitvoerbare bestand wordt gestart en registreert gebeurtenissen op applicatieniveau, onafhankelijk van enig project of batch.
Locatie: %LOCALAPPDATA%\QV2QS\qv2qs.log
Het systeemlogboek gebruikt een roterende bestandsafhandelaar met de volgende instellingen.
| Instelling | Waarde |
|---|---|
| Maximum bestandsgrootte | 25 MB |
| Back-upbestanden bewaard | 3 |
| Bestandspatroon | qv2qs.log, qv2qs.log.1, qv2qs.log.2, qv2qs.log.3 |
Wanneer het actieve logbestand 25 MB bereikt, roteert QV2QS het bestand en maakt een nieuw logbestand aan. De drie meest recente back-ups worden bewaard. Oudere back-ups worden automatisch verwijderd.
Gestructureerd logboek per uitvoering
Elke conversierun produceert een apart logbestand met gedetailleerde gebeurtenissen voor die run. Het bestand heet qv2qs_run_<version>_<timestamp>.log en is geschreven in tab-gescheiden waarden (TSV)-indeling met een JSON-gegevenskolom.
Standaard locatie: %LOCALAPPDATA%\QV2QS\logs\
In de modus voor één project promoot QV2QS het logbestand naar de logs/ submap van de projectuitvoermap (bijvoorbeeld, <outputDir>/Sales/logs/) nadat de uitvoermap is geïnitialiseerd. Het logbestand is opgenomen in de conversie-uitvoer.
In batchmodus, worden logboeken per project geschreven naar de logs/ submap binnen elke uitvoermap van het project.
Logboekbestandindeling
Elk logbestand begint met een TSV-kopregel:
ts_utc level version run_id logger event message data
| Kolom | Beschrijving |
|---|---|
ts_utc
|
ISO 8601 tijdstempel in UTC met milliseconde precisie |
level
|
Logniveau: DEBUG, INFO, WARNING, ERROR, of CRITICAL |
version
|
QV2QS versie |
run_id
|
Unieke uitvoerings-ID in het formaat YYYYMMDD-HHMMSS-<hex> |
logger
|
Loggenaam (meestal qv2qs) |
event
|
Tekenreeks voor gebeurtenistype (bijvoorbeeld, startup, conversion_complete, batch_local_complete) |
message
|
Menselijk leesbare beschrijving |
data
|
JSON-object met contextuele sleutel-waardeparen |
Tijdstempelconflicten
Als twee uitvoeringen binnen dezelfde seconde starten en hetzelfde tijdstempel produceren, voegt QV2QS _2, _3, of opeenvolgende nummers toe aan de bestandsnaam om overschrijven te voorkomen.
Welk logboek controleren
QV2QS schrijft naar twee afzonderlijke logboeken in verschillende fasen van een uitvoering. Het systeemlogboek is altijd beschikbaar. Het logboek per uitvoering wordt pas aangemaakt nadat de initialisatie bij het opstarten is voltooid.
| Scenario | Log om eerst te controleren | Waarom |
|---|---|---|
| Het proces crasht of stopt onmiddellijk | Systeemlogboek | Het logboek per uitvoering is nog niet aangemaakt |
| PRJ-generatie mislukt voordat de conversie begint | Systeemlogboek | PRJ-gebeurtenissen worden gelogd voordat de uitvoermap is geïnitialiseerd |
| Een batchrun toont mislukte bestanden zonder details | Systeemlogboek | Fouten op batchniveau (ontbrekende QlikView Desktop, mislukte vereisten) worden vastgelegd in het systeemlogboek |
| Conversie leidt tot onverwachte uitvoer | Logboek per uitvoering in de uitvoermap | Conversiebeslissingen en -waarschuwingen op objectniveau worden vastgelegd in het logboek per uitvoering |
| Cloud-implementatie mislukt | Logboek per uitvoering in de uitvoermap | API-aanroepen, authenticatiefouten en uploadvoortgang worden vastgelegd in het logboek per uitvoering. |
Het systeemlogboek en het per-uitvoering-logboek leggen dezelfde gebeurtenissen vast tijdens de overlappende periode wanneer beide actief zijn. Het systeemlogboek begint bij de processtart. Het logboek per uitvoering begint nadat opdrachtregelargumenten zijn geparseerd en de uitvoermap is aangemaakt. Als er een storing optreedt voordat het logboek per uitvoering wordt aangemaakt, bevat alleen het systeemlogboek diagnostische informatie.
Logniveaus
Vijf logniveaus zijn beschikbaar, opgesomd van meest naar minst uitgebreid.
| Niveau | Beschrijving |
|---|---|
DEBUG
|
Gedetailleerde diagnostische informatie voor het oplossen van problemen |
INFO
|
Algemene operationele berichten (standaard) |
WARNING
|
Onverwachte omstandigheden die de conversie niet verhinderen |
ERROR
|
Fouten die individuele objecten of bewerkingen beïnvloeden |
CRITICAL
|
Ernstige fouten die de uitvoering doen stoppen |
Stel het logniveau in met --logLevel of de QV2QS_LOG_LEVEL omgevingsvariabele. De CLI-vlag heeft voorrang wanneer beide zijn ingesteld.
Stel --logLevel DEBUG in om de meest gedetailleerde uitvoer vast te leggen. Vermeldingen op debug-niveau omvatten conversiebeslissingen, cloud API-aanroepen, scriptwijzigingen en details van objectverwerking.
Om debug-logboekregistratie in te schakelen zonder de opdrachtregel te wijzigen, stelt u de omgevingsvariabele in voordat u QV2QS uitvoert:
set QV2QS_LOG_LEVEL=DEBUG
QV2QS.exe --prjPath ./MyApp-prj --outputDir ./output --qvw MyApp.qvw --unbuildOnly
Log opschonen
Logbestanden hopen zich op tijdens verschillende uitvoeringen in de persistente logmap. Gebruik --cleanLogs om logbestanden ouder dan 30 dagen te verwijderen bij de start van een uitvoering. De opschoning geldt alleen voor de persistente logmap; logbestanden per project in uitvoermappen blijven onaangetast.
Geheim maskeren
Logboekvermeldingen maskeren automatisch gevoelige waarden. API-sleutels, tokens, wachtwoorden en clientgeheimen worden geredigeerd om alleen de laatste vier tekens te tonen. Opdrachtregelargumenten met geheimen worden ook gemaskeerd wanneer ze worden gelogd.
QlikView Desktop engine-logging
Wanneer PRJ-generatie is ingeschakeld, registreert QV2QS welke QlikView Desktop-engine wordt gebruikt voor elk bestand. De loggebeurtenis prj_generate_start registreert of de gebundelde draagbare engine of een systeem-geïnstalleerde versie actief is en bevat de bestandsversie van het gebundelde uitvoerbare bestand, indien beschikbaar.
Nadat de verbinding met QlikView Desktop tot stand is gebracht, registreert de prj_qv_ready gebeurtenis de QlikView-versie die wordt gerapporteerd door de actieve engine (bijvoorbeeld, 12.100.20100.0). Wanneer de gebundelde engine wordt gebruikt, registreert het exe_file_version veld de bestandsversie die uit het uitvoerbare bestand is gelezen.
In batchmodus registreert de loggebeurtenis prj_batch_prereq de motorselectie en de gebundelde versie voor de hele batch voordat bestanden worden verwerkt. Als er geen gebundelde engine noch een systeeminstallatie beschikbaar is, wordt de fout gelogd als prj_batch_no_qv in het systeemlogboek.
Stel --logLevel DEBUG in om gedetailleerde stappen voor het oplossen van engineproblemen vast te leggen, inclusief de bestandspaden die zijn gecontroleerd tijdens engine-detectie.
Console-uitvoer vs. logboekregistratie in bestand
Console-uitvoer en bestandslogging zijn onafhankelijke systemen.
| Aspect | Console | Bestandslogboek |
|---|---|---|
| Notatie | Opgemaakte tekst met optionele kleuren en spinners | Gestructureerd TSV met JSON-gegevens |
| Beheerd door | --console pretty\|plain\|silent\|ui
|
--logLevel, --logDir |
| Inhoud | Gebruikersgerichte voortgang en resultaten | Volledige diagnostische gebeurtenissen |
| Geheime maskering | Niet van toepassing | Automatisch toegepast |
Console-uitvoer verschijnt niet in de logbestanden. De --console silent vlag onderdrukt console-uitvoer zonder de bestandslogging te beïnvloeden.
CLI-argumenten
| Argument | Beschrijving | Standaard |
|---|---|---|
--logLevel LEVEL
|
Logboek uitgebreidheid: DEBUG, INFO, WARNING, ERROR, CRITICAL |
INFO
|
--logDir FOLDER
|
Overschrijf de loguitvoermap per uitvoering. Relatieve paden worden opgelost vanuit de huidige werkmap, niet vanuit de uitvoermap. Heeft geen invloed op het permanente systeemlogboek op %LOCALAPPDATA%. |
%LOCALAPPDATA%\QV2QS\logs\ (enkel project) of <outputDir>/logs/ (batch) |
--cleanLogs
|
Verwijder logbestanden ouder dan 30 dagen vóór de uitvoering | Uit |