로깅 및 진단

AppPorts에는 앱 런타임 중 핵심 이벤트, 마이그레이션 작업, 시스템 정보 및 오류 세부 사항을 기록하는 내장 로깅 시스템이 있습니다. 문제가 발생하면 진단 패키지를 내보내어 프로젝트 Issues에 제출하여 문제를 해결할 수 있습니다.

기록되는 내용

시작 세션 정보

앱이 시작될 때마다 다음 정보가 기록됩니다:

항목	설명
세션 ID	이번 실행의 고유 식별자 (8자리 UUID 접두사)
프로세스 ID	시스템 프로세스 식별자
Bundle ID	앱 식별자
앱 언어	현재 선택된 언어 코드
시스템 로케일	시스템 로케일 식별자
시간대	현재 시간대 식별자
선호 언어 목록	시스템 선호 언어 순서

시스템 진단 정보

항목	설명
앱 버전	버전 번호 및 빌드 번호
macOS 버전	시스템 버전 및 마케팅 이름 (예: "macOS Sequoia 15.x")
장치 모델	모델 및 친숙한 이름 (예: "MacBook Pro (14-inch, M3 Pro, 2023)")
프로세서 정보	브랜드 문자열, 코어 수, 활성 코어 수
물리적 메모리	총 메모리

외장 저장소 정보

외장 저장소 볼륨을 선택할 때 기록됩니다:

항목	설명
볼륨 이름	저장소 볼륨 이름
총 용량 / 사용 가능 공간	저장소 공간 정보
파일 시스템 형식	예: APFS, HFS+, exFAT 등
인터페이스 프로토콜	USB, Thunderbolt, NVMe/SATA
장치 속도	전송 속도 정보
블록 크기	저장소 블록 크기
볼륨 UUID	저장소 볼륨 고유 식별자

마이그레이션 작업 이벤트

각 마이그레이션 작업은 고유한 작업 ID를 생성합니다 (예: data-migrate-ABCD1234), 다음을 기록:

작업 시작 및 종료
각 단계의 진행률 (복사, 원본 디렉토리 삭제, 심볼릭 링크 생성, 롤백)
단계 전후의 경로 상태 스냅샷 (존재 여부, 권한, 크기, symlink 대상, 불변 플래그)
잔여 마이그레이션 데이터 감지 및 자동 복구
파일 복사 진행률, 오류 및 재시도

마이그레이션 성능 보고서

항목	설명
앱 이름	마이그레이션된 앱 이름
데이터 크기	마이그레이션된 데이터 양
소요 시간	마이그레이션 소요 시간 (초)
전송 속도	전송률 (MB/s)
원본 경로 / 대상 경로	마이그레이션 시작 및 끝 경로

오류 세부 사항

오류 로그에는 구조화된 정보가 포함됩니다:

필드	설명
오류 설명	사람이 읽을 수 있는 오류 설명
오류 유형 / 도메인 / 코드	NSError 구조화 정보
실패 원인	상세한 실패 원인
복구 제안	시스템이 제공하는 복구 제안
파일 경로	영향을 받은 파일 경로
근본 오류	재귀적으로 기록된 중첩 오류

작업 요약

각 마이그레이션 작업은 OperationSummaryRecord를 생성하며, 최근 100개 레코드를 유지합니다:

필드	설명
`operationID`	작업 고유 식별자
`category`	작업 카테고리 (`app_move`, `data-migrate`, `file-copy` 등)
`result`	결과 (`success`, `failed`, `rolled_back`, `success_with_warning`)
`errorCode`	오류 코드 (있는 경우)
`startedAt` / `endedAt`	시작 및 종료 시간
`durationMs`	소요 시간 (밀리초)

로그 설정

저장 위치

기본 로그 경로:

text

~/Library/Application Support/AppPorts/AppPorts_Log.txt

다음을 통해 사용자 정의할 수 있습니다:

메뉴바 → 로그 → 로그 위치 설정
설정 → 로깅 설정 → 사용자 정의 경로

로그 형식

text

[2026-05-08 09:30:00] [INFO] [session:a1b2c3d4] [pid:12345] App started
[2026-05-08 09:30:01] [DIAG] [session:a1b2c3d4] [pid:12345]   app_version: 1.6.1 (123)
[2026-05-08 09:30:05] [PERF] [session:a1b2c3d4] [pid:12345]   Migration complete: 2.3 GB, 45.2 MB/s, 52.1s

로그 레벨

레벨	설명
`INFO`	일반 정보
`ERROR`	오류 정보 (구조화된 오류 세부 사항 포함)
`DIAG`	시스템 진단 정보
`DISK`	외장 저장소 볼륨 정보
`PERF`	마이그레이션 성능 보고서
`TRACE`	하위 수준 경로 상태 및 폴더 모니터링
`DEBUG`	디버그 정보 (크기 계산, 중첩 디렉토리 검사)
`WARN`	경고 (잔여 마이그레이션 데이터, 복구 모드)

로그 로테이션

기본 최대 크기: 2 MB (설정 가능: 1 MB, 5 MB, 10 MB, 50 MB, 100 MB)
초과 시 자동 잘라내기: 이전 절반의 줄을 버리고 새로운 절반을 유지

진단 패키지 내보내기

문제가 발생하여 피드백이 필요한 경우, 진단 패키지를 내보내어 Issue에 첨부해 주세요.

내보내기 방법

방법 1: 메뉴바

메뉴바 → 로그 → 진단 패키지 내보내기를 클릭합니다
저장 위치를 선택합니다
시스템이 자동으로 .zip 파일을 생성하고 Finder에서 엽니다

방법 2: 설정 페이지

AppPorts → 설정 (오른쪽 상단)을 엽니다
"로깅 설정" 섹션을 찾습니다
"진단 패키지 내보내기" 버튼을 클릭합니다
저장 위치를 선택합니다

진단 패키지 내용

내보낸 AppPorts-Diagnostic-<datetime>.zip에는 다음이 포함됩니다:

파일	형식	설명
`diagnostic-summary.json`	JSON	메타데이터 (세션 ID, 버전, 로케일, 시간대 등)
`diagnostic-summary.txt`	일반 텍스트	사람이 읽을 수 있는 진단 요약
`recent-operations.json`	JSON	최근 100개 작업 기록
`recent-failures.json`	JSON	최근 20개 실패/경고 작업
`AppPorts_Log.share-safe.txt`	일반 텍스트	전체 로그 (비식별화됨)

개인정보 보호

진단 패키지의 로그 파일은 비식별화됩니다:

원본 내용	대체 내용
사용자 홈 디렉토리 경로 (예: `/Users/john`)	`/Users/<redacted-user>`
외장 저장소 볼륨 이름 (예: `/Volumes/MyDrive`)	`/Volumes/<redacted-volume>`
`$HOME` 전체 경로	`~`

Issues 제출

진단 패키지를 획득한 후 다음 단계를 따라 제출하세요:

프로젝트 Issues 페이지를 방문합니다
"New Issue"를 클릭하고 Bug report 템플릿을 선택합니다
문제와 재현 단계를 설명합니다
진단 .zip 파일을 첨부 영역에 드래그하여 업로드합니다
Issue를 제출합니다

💡 피드백 효율 향상

진단 패키지와 함께 Issues를 제출하면 문제 해결이 크게 빨라질 수 있습니다. 진단 패키지에는 전체 작업 이력, 오류 세부 사항 및 시스템 환경 정보가 포함되어 있어 개발자가 반복적인 소통 없이도 문제를 재현하고 분석할 수 있습니다.

로깅 및 진단 ​

기록되는 내용 ​

시작 세션 정보 ​

시스템 진단 정보 ​

외장 저장소 정보 ​

마이그레이션 작업 이벤트 ​

마이그레이션 성능 보고서 ​

오류 세부 사항 ​

작업 요약 ​

로그 설정 ​

저장 위치 ​

로그 형식 ​

로그 레벨 ​

로그 로테이션 ​

진단 패키지 내보내기 ​

내보내기 방법 ​

진단 패키지 내용 ​

개인정보 보호 ​

Issues 제출 ​