기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Amazon Q Developer 로그 액세스 및 사용
<a name="troubleshooting-q-logs"></a>

Amazon Q Developer가 생성하는 세부 로그는 문제를 진단하고 해결하는 데 도움이 됩니다. 이 가이드에서는 다양한 Amazon Q 인터페이스의 로그에 액세스하고 문제 해결에 필요한 정보를 가져오도록 로깅 수준을 구성하는 방법을 보여줍니다.

**빠른 탐색:**
+ [로그 액세스 개요](#log-access-overview)
+ [IDE 확장 로그](#ide-logs)
+ [Amazon Q CLI 로그](#cli-logs)
+ [일반적인 로그 패턴 및 솔루션](#common-log-patterns)
+ [로그 분석 도움말 보기](#getting-help-with-logs)

## 로그 액세스 개요
<a name="log-access-overview"></a>

서비스 사용 방식에 따라 Amazon Q Developer 로그에 액세스하는 두 가지 주요 방법이 있습니다.
+ **IDE 확장** - VS Code 및 JetBrains IDE에는 Amazon Q 특정 로그에 액세스하기 위한 ‘로그 표시’ 버튼이 있습니다.
+ **명령줄 인터페이스(Amazon Q CLI)** - 로그는 구성 가능한 세부 수준과 함께 임시 디렉터리에 로컬로 저장됩니다.

**중요**  
로그 파일에는 파일 경로, 코드 조각, 명령 출력, 계정 ID, 리소스 이름 등 Amazon Q와의 대화 및 상호 작용에서 얻은 민감한 정보가 포함될 수 있습니다. 로그 파일을 다른 사람과 공유할 때는 주의해야 합니다.

## IDE 확장 로그
<a name="ide-logs"></a>

### IDE 인터페이스를 통해 로그에 액세스
<a name="ide-logs-ui"></a>

1. IDE(VS Code 또는 JetBrains)에서 Amazon Q 채팅 패널을 엽니다.

1. 채팅 패널의 오른쪽 상단에 있는 **로그 표시** 버튼을 클릭합니다.

1. 나타나는 민감도 경고를 확인합니다.

1. 시스템 파일 관리자에서 검토를 위해 로그 파일 위치가 열립니다.

### IDE 확장 로그 분석
<a name="ide-logs-analysis"></a>

IDE 확장 로그를 검토할 때 다음을 찾습니다.
+ **오류 메시지** - ‘오류’ 또는 ‘치명적’이 포함된 줄은 중요한 문제를 나타냅니다.
+ **인증 문제** - 인증 또는 자격 증명 관련 오류를 찾습니다.
+ **네트워크 연결** - 연결 제한 시간 또는 네트워크 관련 오류
+ **기능별 오류** - 코드 제안, 채팅 또는 기타 특정 기능과 관련된 문제

## Amazon Q CLI 로그
<a name="cli-logs"></a>

Amazon Q CLI는 세부 정보 설정에 관계없이 모든 작업에 대한 포괄적인 로그를 자동으로 생성합니다. 로그는 항상 파일에 기록되지만 세부 정보 플래그는 터미널 출력에 표시되는 항목만 제어합니다.

### Amazon Q CLI 로그 위치 및 파일
<a name="cli-log-locations"></a>

Amazon Q CLI 로그는 다음 위치에 자동으로 저장됩니다.


| 운영 체제 | 로그 위치 | 
| --- | --- | 
| macOS | \$1TMPDIR/qlog/(일반적으로 /var/folders/.../qlog/) | 
| Linux/WSL | \$1XDG\$1RUNTIME\$1DIR/qlog/, \$1TMPDIR/qlog/ 또는 /tmp/qlog/ | 
| Windows | %TEMP%\$1qlog\$1 | 

Amazon Q CLI는 여러 특수 로그 파일을 자동으로 생성합니다.

`chat.log` - 다음을 포함한 **기본 Amazon Q CLI 래퍼 로그**:  
+ Amazon Q CLI 초기화 및 시작 작업
+ AWS SDK 호출(Cognito 자격 증명, 인증 흐름)
+ 네트워크 작업(HTTP/TLS 연결, 인증서 처리)
+ 하위 수준 시스템 작업(원격 측정, 소켓 연결)
+ AWS 서비스 엔드포인트 확인 및 연결 풀링
+ 인프라 구성 요소에 대한 세부 디버깅 정보

`qchat.log` - 다음을 포함한 **채팅 애플리케이션별 로그**:  
+ 채팅 애플리케이션 오류 및 상태 처리 문제
+ MCP(모델 컨텍스트 프로토콜) 서버 관리 및 연결 오류
+ 애플리케이션 수준 마이그레이션 문제
+ 사용자 상호 작용 중단 및 채팅 처리 실패
+ 상위 수준 애플리케이션 로직 오류

`mcp.log` - 모델 컨텍스트 프로토콜 서버 로그(MCP 서버를 사용할 때 채워짐)  

`translate.log` - 번역 로그를 쉘링하는 자연어(번역 기능을 사용할 때 채워짐)  

#### 로그 파일 간 주요 차이점
<a name="cli-log-file-differences"></a>

**범위 및 세부 정보 차이점:**
+ `chat.log`: 전체 Q CLI 인프라를 다루는 포괄적인 시스템 수준 로깅
+ `qchat.log`: 채팅 기능별 집중 애플리케이션 수준 로깅

**콘텐츠 포커스 차이점:**
+ `chat.log`: AWS SDK 내부, 네트워킹 프로토콜, 인증 흐름, 시스템 작업
+ `qchat.log`: 채팅 로직, MCP 서버 수명 주기, 사용자 경험 문제, 애플리케이션 오류

**참고**  
로그 파일은 로컬 시스템에만 저장되며 로 전송되지 않습니다 AWS. 모든 로그 파일은 상세 표시 플래그 없이도 CLI를 처음 사용할 때 자동으로 생성됩니다.

### Amazon Q CLI 문제 해결 워크플로
<a name="cli-troubleshooting-workflow"></a>

이 접근 방식을 따라 로그에서 진단 정보를 수집합니다.

1. 시스템의 로그 디렉터리를 다음과 같이 식별합니다.

   Linux/WSL:

   ```
   echo $XDG_RUNTIME_DIR/qlog/
   ```

   macOS:

   ```
   echo $TMPDIR/qlog/
   ```

   Windows의 경우:

   ```
   echo %TEMP%\qlog\
   ```

1. Amazon Q CLI 명령을 최대한 세부적으로 실행하여 터미널의 세부 출력을 확인합니다.

   ```
   q -vvv chat
   ```

1. 현재 겪고 있는 문제를 재현합니다.

1. Amazon Q CLI를 종료하고 관련 로그 파일을 검사합니다. 대부분의 문제에서는 두 기본 로그 파일을 모두 확인합니다.

   macOS/Linux:

   ```
   less -r $XDG_RUNTIME_DIR/qlog/qchat.log
   less -r $XDG_RUNTIME_DIR/qlog/chat.log
   ```

   macOS의 대안:

   ```
   less -r $TMPDIR/qlog/qchat.log
   less -r $TMPDIR/qlog/chat.log
   ```

   Windows의 경우:

   ```
   type %TEMP%\qlog\qchat.log
   type %TEMP%\qlog\chat.log
   ```

1. 문제 해결 중 실시간 로그 모니터링의 경우 다음을 사용합니다.

   모든 로그 파일을 동시에 모니터링합니다.

   ```
   tail -f $XDG_RUNTIME_DIR/qlog/*.log
   ```

   특정 파일을 모니터링합니다.

   ```
   tail -f $XDG_RUNTIME_DIR/qlog/qchat.log
   ```

   ```
   tail -f $XDG_RUNTIME_DIR/qlog/chat.log
   ```

### Amazon Q CLI 로그 분석
<a name="cli-log-analysis"></a>

Amazon Q CLI 로그는 표준 로깅 수준을 사용하여 중요도별로 정보를 분류합니다.

오류  
정상 작동을 방해하는 중요한 문제 - 문제 해결 시 여기에서 시작

WARN  
기능을 중지하지는 않지만 주의해야 하는 잠재적 문제

INFO  
애플리케이션이 수행하는 작업에 대한 일반 운영 메시지

DEBUG  
심층 조사에 유용한 세부 기술 정보

Amazon Q CLI 로그를 검사할 때는 다양한 로그 파일의 다음 주요 영역에 집중하세요.

`qchat.log` 분석 - 다음을 포함한 애플리케이션 수준 문제:  
+ **ERROR chat\$1cli::cli::chat** - 채팅 처리 및 상태 관리 오류
+ **ERROR chat\$1cli::cli::agent** - 마이그레이션 및 에이전트 관련 문제
+ **ERROR chat\$1cli::telemetry** - 원격 측정 검증 및 전송 실패

`chat.log` 분석 - 다음을 포함한 런타임 운영 세부 정보:  
+ **DEBUG q\$1cli::cli** - Amazon Q CLI 명령 실행 및 초기화
+ **DEBUG aws\$1sdk\$1\$1** - AWS SDK 작업 및 서비스 호출
+ **DEBUG rustls::\$1** - TLS/SSL 연결 설정 및 인증서 처리
+ **DEBUG hyper\$1\$1** - HTTP 연결 관리 및 네트워크 작업
+ **ERROR fig\$1telemetry** - 시스템 원격 측정 및 소켓 연결 문제

일반 분석 팁:
+ **타임스탬프** - 문제가 발생한 경우 로그 항목과 연결
+ **오류 패턴** - 반복되는 오류 또는 오류 캐스케이드 찾기
+ **요청 ID** - 특정 API 직접 호출 및 호출 결과 추적
+ **연결 상태** - 네트워크 연결 및 인증 상태 모니터링

**작은 정보**  
검색 기능이 있는 **grep**, **awk** 또는 텍스트 편집기와 같은 도구를 사용하여 로그에서 특정 오류 메시지 또는 패턴을 필터링합니다. 예: **grep -i error \$1XDG\$1RUNTIME\$1DIR/qlog/\$1.log**

## 일반적인 로그 패턴 및 솔루션
<a name="common-log-patterns"></a>

다음은 로그에서 발견할 수 있는 몇 가지 일반적인 문제와 일반적인 해결 방법입니다.

MCP 서버 연결 오류  
**로그 패턴(qchat.log):** "클라이언트 [server-name]의 배경 수신 스레드: RecvError(닫힘)" 또는 "전송 계층을 위해 삭제된 모든 발신자"  
**해결 방법:** MCP 서버 프로세스 실행이 중지되었습니다. 이는 일반적으로 Amazon Q CLI를 종료하거나 서버가 정상적으로 종료될 때 예상되는 동작입니다.

채팅 처리 중단  
**로그 패턴(qchat.log):** "현재 상태 err=Interrupted \$1 tool\$1uses: None \$1를 처리하는 동안 오류가 발생했습니다."  
**해결 방법:** 사용자가 채팅 작업을 취소하면(예: Ctrl\$1C) 발생하며 이는 예상되는 동작입니다.

원격 측정 검증 오류  
**로그 패턴(qchat.log):** "cw 원격 측정 이벤트 err=ValidationError [ValidationException]: 잘못 구성된 요청 전송 실패"  
**해결 방법:** 일반적으로 중요하지 않은 원격 측정 전송 문제로, 핵심 기능에 영향을 주지 않습니다.

마이그레이션 경고  
**로그 패턴(qchat.log):** "다음의 이유로 마이그레이션이 발생하지 않음: 마이그레이션 중단"  
**해결 방법:** 일반적으로 구성 마이그레이션과 관련된 중요하지 않은 경고이며 대개는 무시할 수 있습니다.

인증 실패 횟수  
**로그 패턴(chat.log):** AWS SDK 작업의 인증 관련 오류  
**솔루션:** **q login**을 실행하여 AWS 자격 증명을 다시 인증하거나 확인합니다.

네트워크 연결 이벤트  
**로그 패턴(chat.log):** "연결 제한 시간", "네트워크에 연결할 수 없음" 또는 HTTP 연결 실패  
**해결 방법:** 네트워크 연결 및 방화벽 설정을 확인합니다.

AWS SDK 작업 실패  
**로그 패턴(chat.log):** Cognito 자격 증명 작업 실패 또는 자격 증명 검색 오류  
**해결 방법:** AWS 자격 증명 및 네트워크 연결을 확인합니다. 재인증이 필요할 수 있음

## 로그 분석 도움말 보기
<a name="getting-help-with-logs"></a>

로그 분석 또는 문제 해결에 도움이 필요한 경우 다음을 수행합니다.
+ 지원 팀에 문의할 때 관련 로그 발췌문 포함(민감한 정보 제거됨)
+ 문제가 언제 발생하는지에 대한 컨텍스트와 문제 재현 단계를 제공합니다.