# 日誌記錄與診斷

QV2QS 每次執行時都會寫入結構化診斷日誌。記錄系統有兩個層級：一個持久的系統日誌，可在多次執行後仍保留；以及一個隨每次執行生成的結構化日誌，會與轉換輸出一起提供。

## 系統日誌

QV2QS 在磁碟上的固定位置保留一個滾動日誌檔案。系統日誌在可執行檔啟動時開始，並記錄獨立於任何專案或批次的應用程式層級事件。

地點： `%LOCALAPPDATA%\QV2QS\qv2qs.log`

系統日誌使用具有以下設定的輪替檔案處理器。

| 設定 | 值 |
| --- | --- |
| 檔案大小上限 | 25 MB |
| 備份檔案保留 | 3 |
| 檔案模式 | `qv2qs.log`, `qv2qs.log.1`, `qv2qs.log.2`, `qv2qs.log.3` |

當作用中記錄檔達到 25 MB 時，QV2QS 會輪替該檔案並建立新的記錄檔。保留最近的三個備份。較舊的備份會自動刪除。

## 每次執行結構化日誌

每次轉換執行都會產生一個單獨的記錄檔，其中包含該次執行的詳細事件。檔案命名為 `qv2qs_run_<version>_<timestamp>.log`，並採用索引標籤分隔值 (TSV) 格式，其中包含 JSON 資料欄位。

預設位置: `%LOCALAPPDATA%\QV2QS\logs\`

在單一專案模式下，QV2QS 會在輸出資料夾初始化後，將日誌檔提升到專案輸出資料夾的 `logs/` 子資料夾中 (例如，`<outputDir>/Sales/logs/`)。記錄檔已包含在轉換輸出中。

在批次模式中，各專案的日誌會寫入到每個專案輸出資料夾內的 `logs/` 子資料夾。

### 記錄檔格式

每個日誌檔案都以 TSV 標頭列開頭：

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

| 欄 | 描述 |
| --- | --- |
| `ts_utc` | ISO 8601 時間戳記，UTC 毫秒精確度 |
| `level` | 日誌級別：`DEBUG`、`INFO`、`WARNING`、`ERROR` 或 `CRITICAL` |
| `version` | QV2QS 版本 |
| `run_id` | 獨特的執行識別碼，格式為`YYYYMMDD-HHMMSS-<hex>` |
| `logger` | 記錄器名稱 (通常為 `qv2qs`) |
| `event` | 事件類型字串 (例如，`startup`，`conversion_complete`，`batch_local_complete`) |
| `message` | 人類可讀的描述 |
| `data` | 包含上下文相關鍵值對的 JSON 物件 |

### 時間戳記衝突

如果兩個執行在同一秒內啟動並產生相同的時間戳記，QV2QS 會將 `_2`、`_3` 或後續數字附加到檔案名稱，以避免覆寫。

## 要檢查哪個日誌

QV2QS 在執行過程的不同階段，寫入兩個獨立的日誌。系統日誌始終可用。每次執行的日誌只會在啟動初始化完成後建立。

| 情境 | 先檢查日誌 | 為什麼 |
| --- | --- | --- |
| 該程序崩潰或立即退出 | 系統日誌 | 單次執行的日誌尚未建立 |
| PRJ 生成在轉換開始前失敗 | 系統日誌 | PRJ 事件會在輸出目錄初始化前記錄。 |
| 批次執行顯示失敗的檔案，無詳細資料 | 系統日誌 | 批次層級錯誤 (缺少 QlikView Desktop、先決條件失敗) 會記錄在系統日誌中 |
| 轉換產生非預期的輸出 | 輸出目錄中的每次執行日誌 | 物件層級的轉換決策和警告會被記錄在每次執行的記錄檔中 |
| 雲端部署失敗 | 輸出目錄中的每次執行日誌 | API 呼叫、驗證錯誤以及上傳進度會記錄在每次執行的記錄檔中 |

資訊備註

系統日誌和每次執行日誌在兩者都作用中時，會於重疊期間記錄相同的事件。系統日誌在程序啟動時開始。單次執行日誌會在命令列引數解析完畢且輸出目錄建立完成後開始。如果在每次執行記錄檔建立之前發生故障，則只有系統記錄檔會包含診斷資訊。

## 日誌級別

提供五個日誌級別，從最詳細到最不詳細的順序列出。

| 層級 | 描述 |
| --- | --- |
| `DEBUG` | 為疑難排解的詳細診斷資訊 |
| `INFO` | 一般操作訊息 (預設) |
| `WARNING` | 不會阻止轉換的意外狀況 |
| `ERROR` | 影響個別物件或操作的失敗 |
| `CRITICAL` | 嚴重故障，導致執行停止 |

使用 `--logLevel` 或 `QV2QS_LOG_LEVEL` 環境變數設定日誌層級。當兩者皆設定時，CLI 旗標會優先。

設定 `--logLevel DEBUG` 以擷取最詳細的輸出。偵錯層級項目包含轉換決策、雲端 API 呼叫、指令碼修改和物件處理詳細資料。

若要在不修改命令列的情況下啟用偵錯記錄，請設定環境變數再執行 QV2QS：

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

## 日誌清理

記錄檔會在永久記錄目錄中，隨著多次執行而累積。使用 `--cleanLogs` 在執行開始時刪除超過 30 天的日誌檔案。此清理僅適用於持久性日誌目錄；輸出目錄中的每個專案日誌不受影響。

## 秘密遮罩

日誌項目會自動遮罩敏感值。API 金鑰、權杖、密碼和用戶端密碼已遮蔽，僅顯示最後四個字元。包含機密的命令列引數，在記錄時也會被遮罩。

## QlikView 桌面版引擎記錄

當 PRJ 產生功能啟用時，QV2QS 會記錄每個檔案使用了哪個 QlikView Desktop 引擎。記錄事件 `prj_generate_start` 記錄了搭售的可攜式引擎或系統安裝版本是否為作用中，並在可用時包含搭售可執行檔的檔案版本。

與 QlikView Desktop 的連線建立後，`prj_qv_ready` 事件會記錄由執行中的引擎回報的 QlikView 版本 (例如，`12.100.20100.0`)。當使用內建引擎時，`exe_file_version` 欄位會記錄從可執行檔讀取的檔案版本。

在批次模式下，日誌事件 `prj_batch_prereq` 會在處理任何檔案之前，記錄整個批次的引擎選擇和綁定版本。如果沒有可用的捆綁引擎或系統安裝，錯誤會記錄為 `prj_batch_no_qv` 在系統日誌中。

設定 `--logLevel DEBUG` 以擷取詳細的引擎解析步驟，包括在引擎探索期間檢查的檔案路徑。

## 主控台輸出與檔案記錄

控制台輸出與檔案記錄是獨立的系統。

| 方面 | 主控台 | 檔案日誌 |
| --- | --- | --- |
| 格式 | 格式化文字，可選顏色和旋轉圖示 | 結構化 TSV 搭配 JSON 資料 |
| 由...控制 | `--console pretty\\|plain\\|silent\\|ui` | `--logLevel`, `--logDir` |
| 內容 | 面向使用者的進度與結果 | 完成診斷事件 |
| 機密遮罩 | 不適用 | 自動套用 |

主控台輸出不會顯示在日誌檔案中。此 `--console silent` 旗標會抑制主控台輸出，而不影響檔案記錄。

## CLI 引數

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--logLevel LEVEL` | 日誌詳細程度： `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | `INFO` |
| `--logDir FOLDER` | 覆寫每次執行的日誌輸出資料夾。相對路徑是從目前工作目錄解析，而非從輸出目錄解析。不會影響位於 `%LOCALAPPDATA%` 的持久系統日誌。 | `%LOCALAPPDATA%\QV2QS\logs\` (單一專案) 或 `<outputDir>/logs/` (批次) |
| `--cleanLogs` | 執行前刪除超過 30 天的日誌檔案 | 關閉 |

## 了解更多

* [引數參考](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [疑難排解](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/troubleshooting/index.htm)