# 日志记录和诊断

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-CN/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [故障排除](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/troubleshooting/index.htm)