# 로깅 및 진단

QV2QS는 모든 실행 중에 구조화된 진단 로그를 작성합니다.로깅 시스템은 두 가지 계층을 가집니다: 실행 간에도 유지되는 영구 시스템 로그와 변환 출력과 함께 제공되는 실행별 구조화된 로그입니다.

## 시스템 로그

QV2QS는 디스크의 고정된 위치에 롤링 로그 파일을 유지합니다.시스템 로그는 실행 파일이 시작될 때 시작되며, 프로젝트나 배치와는 독립적으로 애플리케이션 수준 이벤트를 기록합니다.

위치: `%LOCALAPPDATA%\QV2QS\qv2qs.log`

시스템 로그는 다음 설정을 사용하여 순환 파일 핸들러를 사용합니다.

| 설정 | 값 |
| --- | --- |
| 최대 파일 크기 | 25MB |
| 백업 파일 보관됨 | 3 |
| 파일 패턴 | `qv2qs.log`, `qv2qs.log.1`, `qv2qs.log.2`, `qv2qs.log.3` |

활성 로그 파일이 25MB에 도달하면, 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 객체 |

### 타임스탬프 충돌

두 개의 실행이 같은 초 내에 시작되고 동일한 타임스탬프를 생성하는 경우, QV2QS는 덮어쓰기를 방지하기 위해 파일 이름에 `_2`, `_3` 또는 그 이후의 숫자를 추가합니다.

## 확인할 로그

QV2QS는 실행의 여러 단계에서 두 개의 개별 로그에 기록합니다.시스템 로그는 항상 이용 가능합니다.실행별 로그는 시작 초기화가 완료된 후에만 생성됩니다.

| 시나리오 | 먼저 확인할 로그 | 이유가 무엇입니까? |
| --- | --- | --- |
| 프로세스가 충돌하거나 즉시 종료됩니다 | 시스템 로그 | 실행별 로그가 아직 생성되지 않았습니다. |
| 변환이 시작되기 전에 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
```

## 로그 정리

로그 파일은 영구 로그 디렉터리에 실행 전반에 걸쳐 누적됩니다.실행 시작 시 30일 이상 된 로그 파일을 삭제하려면 `--cleanLogs`을(를) 사용하세요.정리 작업은 영구 로그 디렉터리에만 적용되며, 출력 디렉터리의 프로젝트별 로그는 영향을 받지 않습니다.

## 비밀 마스킹

로그 항목은 민감한 값을 자동으로 마스킹합니다.API 키, 토큰, 비밀번호 및 클라이언트 보안 비밀은 마지막 네 자리만 표시되도록 가려집니다.비밀이 포함된 명령줄 인수도 로깅될 때 마스킹됩니다.

## QlikView Desktop 엔진 로깅

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/ko-KR/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)
* [문제 해결](https://help.qlik.com/ko-KR/migration/Content/Qv2qsMigration/troubleshooting/index.htm)