# ログと診断

QV2QS は実行ごとに構造化された診断ログを書き込みます。ロギングシステムには2つの階層があります。実行をまたいで存続する永続的なシステムログと、変換出力に同梱される実行ごとの構造化ログです。

## システムログ

QV2QS はディスク上の固定された場所でローリングログファイルを維持します。システムログは、実行可能ファイルが起動すると開始され、いかなるプロジェクトやバッチからも独立して、アプリケーションレベルのイベントを記録します。

場所: `%LOCALAPPDATA%\QV2QS\qv2qs.log`

システムログは、以下の設定でローテーションファイルハンドラーを使用します。

| 設定 | 値 |
| --- | --- |
| 最大ファイル サイズ | 25 MB |
| バックアップファイル保持 | 3 |
| ファイルパターン | `qv2qs.log`, `qv2qs.log.1`, `qv2qs.log.2`, `qv2qs.log.3` |

アクティブなログファイルが25 MBに達すると、QV2QSはそのファイルをローテーションし、新しいログファイルを作成します。直近3つのバックアップが保持されます。古いバックアップは自動的に削除されます。

## 実行ごとの構造化ログ

変換の実行ごとに、その実行の詳細なイベントを含む個別のログファイルが生成されます。ファイル名は`qv2qs_run_<version>_<timestamp>.log`で、JSONデータ列を含むタブ区切り値 (TSV) 形式で記述されています。

既定の場所: `%LOCALAPPDATA%\QV2QS\logs\`

シングルプロジェクトモードでは、出力フォルダーが初期化された後、QV2QSはログファイルをプロジェクト出力フォルダーの`logs/`サブフォルダー (例: `<outputDir>/Sales/logs/`) に昇格させます。ログファイルは変換出力に含まれています。

バッチモードでは、プロジェクトごとのログは、各プロジェクトの出力フォルダー内の`logs/` サブフォルダーに書き込まれます。

### ログファイル形式

各ログファイルはTSVヘッダー行で始まります:

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

| 列 | 説明 |
| --- | --- |
| `ts_utc` | UTCでのミリ秒精度のISO 8601タイムスタンプ |
| `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オブジェクト |

### タイムスタンプの衝突

2つの実行が同じ秒内に開始され、同じタイムスタンプを生成する場合、QV2QSは、上書きを避けるために、ファイル名に`_2`、`_3`、またはそれ以降の番号を追加します。

## どのログを確認しますか

QV2QS は、実行の異なる段階で、2つの別々のログに書き込みます。システムログは常に利用可能です。実行ごとのログは、起動時の初期化が完了した後にのみ作成されます。

| シナリオ | 最初に確認するログ | なぜでしょうか? |
| --- | --- | --- |
| プロセスがクラッシュするか、すぐに終了します | システム ログ | 実行ごとのログはまだ作成されていません |
| PRJ生成は変換開始前に失敗します | システム ログ | 出力ディレクトリが初期化される前に、PRJ イベントがログに記録されます |
| バッチ実行で失敗したファイルが表示されますが、詳細はありません | システム ログ | バッチレベルのエラー (QlikView Desktop が見つからない、前提条件の失敗など) はシステムログに記録されます |
| 変換で予期しない出力になる | 出力ディレクトリ内の実行ごとのログ | オブジェクトレベルの変換決定と警告は、実行ごとのログに記録されます |
| クラウド展開に失敗しました | 出力ディレクトリ内の実行ごとのログ | API呼び出し、認証エラー、およびアップロードの進行状況は、実行ごとのログに記録されます |

情報メモ

システムログと実行ごとのログは、両方がアクティブな重複期間中に同じイベントを記録します。システムログはプロセス起動時に開始されます。コマンドライン引数が解析され、出力ディレクトリが作成された後に、実行ごとのログが開始されます。実行ごとのログが作成される前に障害が発生した場合、システムログのみが診断情報を含みます。

## ログレベル

5つのログレベルが利用可能で、詳細度が高い順から低い順にリストされています。

| レベル | 説明 |
| --- | --- |
| `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キー、トークン、パスワード、およびクライアントシークレットは、最後の4文字のみが表示されるように伏せられています。シークレットを含むコマンドライン引数も、ログに記録される際にマスクされます。

## 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` を、エンジン検出中にチェックされたファイルパスを含む詳細なエンジン解決手順をキャプチャするように設定します。

## コンソール出力 対 ファイルロギング

コンソール出力とファイルログは独立したシステムです。

| 側面 | コンソール | ファイルログ |
| --- | --- | --- |
| 形式 | オプションの色とスピナー付きのフォーマットされたテキスト | JSONデータ付き構造化TSV |
| 制御元 | `--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/ja-JP/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [トラブルシューティング](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/troubleshooting/index.htm)