存取和使用 Amazon Q Developer 日誌 - Amazon Q Developer
日誌存取概觀IDE 延伸模組日誌Amazon Q CLI 日誌常見日誌模式和解決方案協助進行日誌分析

存取和使用 Amazon Q Developer 日誌

Amazon Q Developer 會產生詳細的日誌，協助您診斷和解決問題。本指南說明如何存取不同 Amazon Q 介面的日誌，並設定日誌層級以取得故障診斷所需的資訊。

快速導覽：

日誌存取概觀

根據您使用服務的方式而定，有兩種主要方式可存取 Amazon Q Developer 日誌：

  • IDE 延伸模組 - VS Code 和 JetBrains IDE 有「顯示日誌」按鈕，可用於存取 Amazon Q 特定日誌

  • 命令列介面 (Amazon Q CLI) - 日誌會儲存在本機上的暫存目錄中，且可設定細節層級

重要

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

IDE 延伸模組日誌

透過 IDE 介面存取日誌

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

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

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

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

分析 IDE 延伸模組日誌

檢閱 IDE 延伸模組日誌時，請尋找：

  • 錯誤訊息 - 包含「ERROR」或「FATAL」的行表示有重大問題

  • 身分驗證問題 - 尋找身分驗證或憑證相關的錯誤

  • 網路連線 - 連線逾時或網路相關錯誤

  • 功能特定錯誤 - 與程式碼建議、聊天或其他特定功能相關的問題

Amazon Q CLI 日誌

無論詳細程度設定為何，Amazon Q CLI 都會自動針對所有操作產生完整的日誌。日誌一律寫入檔案中，而詳細程度旗標僅控制終端輸出中顯示的內容。

Amazon Q CLI 日誌位置和檔案

Amazon Q CLI 日誌會自動儲存在下列位置：

作業系統 日誌位置
macOS $TMPDIR/qlog/ (通常是 /var/folders/.../qlog/)
Linux/WSL $XDG_RUNTIME_DIR/qlog/、$TMPDIR/qlog/ 或 /tmp/qlog/
Windows %TEMP%\qlog\

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 日誌 (使用轉譯功能時填入)

日誌檔案之間的主要差異

範圍和細節差異：

  • chat.log：完整的系統層級記錄，涵蓋整個 Q CLI 基礎結構

  • qchat.log：聊天功能特定的集中應用程式層級記錄

內容焦點差異：

  • chat.log：AWS SDK 內部、聯網通訊協定、身分驗證流程、系統操作

  • qchat.log：聊天邏輯、MCP 伺服器生命週期、使用者體驗問題、應用程式錯誤

注意

日誌檔案只會儲存在本機上，不會傳送至 AWS。所有日誌檔案都會在您第一次使用 CLI 時自動建立，即使沒有詳細程度旗標也一樣。

Amazon Q CLI 故障診斷工作流程

依照此方法從日誌收集診斷資訊。

  1. 識別您系統的日誌目錄：

    在 Linux/WSL 上：

    echo $XDG_RUNTIME_DIR/qlog/

    在 macOS 上：

    echo $TMPDIR/qlog/

    在 Windows 上：

    echo %TEMP%\qlog\

  2. 以最大詳細程度執行 Amazon Q CLI 命令，以便在終端查看詳細的輸出：

    q -vvv chat

  3. 重現您遇到的問題

  4. 退出 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

  5. 對於故障診斷期間的即時日誌監控，請使用：

    同時監控所有日誌檔案：

    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 日誌

Amazon Q CLI 日誌使用標準記錄層級依重要性將資訊分類：

ERROR

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

WARN

未停止功能但應注意的潛在問題

INFO

有關應用程式執行狀況的一般操作訊息

DEBUG

詳細的技術資訊有助於深入調查

查看 Amazon Q CLI 日誌時，聚焦不同日誌檔案中的這些重要區域：

qchat.log 分析 - 應用程式層級問題，包括：

  • ERROR chat_cli::cli::chat - 聊天處理和狀態管理錯誤

  • ERROR chat_cli::cli::agent - 移轉和代理程式相關問題

  • ERROR chat_cli::telemetry - 遙測驗證和傳輸失敗

chat.log 分析 - 執行時期操作詳細資訊，包括：

  • DEBUG q_cli::cli - Amazon Q CLI 命令執行和初始化

  • DEBUG aws_sdk_* - AWS SDK 操作和服務呼叫

  • DEBUG rustls::* - TLS/SSL 連線建立和憑證處理

  • DEBUG hyper_* - HTTP 連線管理和網路操作

  • ERROR fig_telemetry - 系統遙測和通訊端連線問題

一般分析秘訣：

  • 時間戳記 - 將日誌項目與問題發生時間相互關聯

  • 錯誤模式 - 尋找重複的錯誤或錯誤串聯

  • 請求 ID - 追蹤特定 API 呼叫及其結果

  • 連線狀態 - 監控網路連線和身分驗證狀態

提示

使用 grep、awk 或文字編輯器等工具搭配搜尋功能來篩選日誌，以找出特定錯誤訊息或模式。例如：grep -i error $XDG_RUNTIME_DIR/qlog/*.log

常見日誌模式和解決方案

以下是您可能會在日誌中發現的一些常見問題及其典型解決方案：

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 { tool_uses: None }」(處理目前狀態 err=已中斷 { tool_uses: 無 } 時發生錯誤)

解決方案：這是在使用者取消聊天操作 (例如 Ctrl+C) 時發生，且為預期行為。

遙測驗證錯誤

日誌模式 (在 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 憑證和網路連線。可能需要重新進行身分驗證

協助進行日誌分析

若需要協助您分析日誌或解決問題：

  • 聯絡支援時，請包含相關的日誌摘錄 (將敏感資訊移除)

  • 提供問題發生的時間和重現問題的步驟等相關內容