本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 存取和使用 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)** - 日誌會儲存在本機上的暫存目錄中，且可設定細節層級

**重要**  
日誌檔案可能包含您與 Amazon Q 的對話和互動中的敏感資訊，包括檔案路徑、程式碼片段、命令輸出、帳戶 ID 及資源名稱。與他人共用日誌檔案時務必謹慎。

## IDE 延伸模組日誌
<a name="ide-logs"></a>

### 透過 IDE 介面存取日誌
<a name="ide-logs-ui"></a>

1. 在 IDE 中開啟 Amazon Q 聊天面板 (VS Code 或 JetBrains)

1. 按一下聊天面板右上角的**顯示日誌**按鈕

1. 確認出現的敏感性警告

1. 日誌檔案位置會在您系統的檔案管理員中開啟以供檢閱

### 分析 IDE 延伸模組日誌
<a name="ide-logs-analysis"></a>

檢閱 IDE 延伸模組日誌時，請尋找：
+ **錯誤訊息** - 包含「ERROR」或「FATAL」的行表示有重大問題
+ **身分驗證問題** - 尋找身分驗證或憑證相關的錯誤
+ **網路連線** - 連線逾時或網路相關錯誤
+ **功能特定錯誤** - 與程式碼建議、聊天或其他特定功能相關的問題

## 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 Identity、身分驗證流程)
+ 網路操作 (HTTP/TLS 連線、憑證處理)
+ 低階系統操作 (遙測、通訊端連線)
+ AWS 服務端點解析和連線集區
+ 基礎結構元件的詳細偵錯資訊

`qchat.log` - **聊天應用程式特定的日誌**，包括：  
+ 聊天應用程式錯誤和狀態處理問題
+ MCP (模型上下文通訊協定) 伺服器管理和連線錯誤
+ 應用程式層級移轉問題
+ 使用者互動中斷和聊天處理失敗
+ 更高階的應用程式邏輯錯誤

`mcp.log` - 模型上下文通訊協定伺服器日誌 (使用 MCP 伺服器時填入)  

`translate.log` - 自然語言轉譯 Shell 日誌 (使用轉譯功能時填入)  

#### 日誌檔案之間的主要差異
<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 日誌使用標準記錄層級依重要性將資訊分類：

ERROR  
妨礙正常操作的重大問題 - 故障診斷時從這裡開始

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 中)**："Background listening thread for client [server-name]: RecvError(Closed)" (用戶端 [server-name] 的背景接聽執行緒: RecvError(Closed)) 或 "All senders dropped for transport layer" (傳輸層的所有傳送者已斷線)  
**解決方案：**MCP 伺服器程序已停止執行。這通常是退出 Amazon Q CLI 或伺服器正常關閉時的預期行為。

聊天處理中斷  
**日誌模式 (在 qchat.log 中)**："An error occurred processing the current state err=Interrupted \$1 tool\$1uses: None \$1" (處理目前狀態 err=已中斷 \$1 tool\$1uses: 無 \$1 時發生錯誤)  
**解決方案：**這是在使用者取消聊天操作 (例如 Ctrl\$1C) 時發生，且為預期行為。

遙測驗證錯誤  
**日誌模式 (在 qchat.log 中)：**"Failed to send cw telemetry event err=ValidationError [ValidationException]: Improperly formed request" (無法傳送 cw 遙測事件 err=ValidationError [ValidationException]: 請求格式不正確)  
**解決方案：**這些通常是非重大遙測傳輸問題，不會影響核心功能。

移轉警告  
**日誌模式 (在 qchat.log 中)：**"Migration did not happen for the following reason: Aborting migration" (移轉未發生，原因如下：中止移轉)  
**解決方案：**這一般是與組態移轉相關的非重大警告，通常可以忽略。

身分驗證失敗  
**日誌模式 (在 chat.log 中)：**AWS SDK 操作中發生身分驗證相關錯誤  
**解決方案：**執行 **q login** 以重新驗證身分，或檢查您的 AWS 憑證

網路連線問題  
**日誌模式 (在 chat.log 中)：**「連線逾時」、「網路無法連線」或 HTTP 連線失敗  
**解決方案：**檢查您的網際網路連線和防火牆設定

AWS SDK 操作失敗  
**日誌模式 (在 chat.log 中)：**Cognito Identity 操作失敗，或憑證擷取錯誤  
**解決方案：**檢查您的 AWS 憑證和網路連線。可能需要重新進行身分驗證

## 協助進行日誌分析
<a name="getting-help-with-logs"></a>

若需要協助您分析日誌或解決問題：
+ 聯絡支援時，請包含相關的日誌摘錄 (將敏感資訊移除)
+ 提供問題發生的時間和重現問題的步驟等相關內容