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

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

存取和使用 Amazon Q Developer 日誌

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

快速導覽：

日誌存取概觀

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

  • IDE 延伸模組 - VS 程式碼和 JetBrains IDEs 具有用於存取 Amazon Q 特定日誌的「顯示日誌」按鈕

  • 命令列界面 (Amazon Q CLI) - 日誌會以可設定的詳細資訊層級儲存在本機暫存目錄中

重要

日誌檔案可能包含來自您與 Amazon Q 對話和互動的敏感資訊，包括檔案路徑、程式碼片段、命令輸出、帳戶 IDs 和資源名稱。與他人共用日誌檔案時請小心。

IDE 延伸日誌

透過 IDE 界面存取日誌

  1. 在您的 IDE 中開啟 Amazon Q 聊天面板 (VS 程式碼或 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 開發套件呼叫 (Cognito Identity、身分驗證流程）

  • 網路操作 (HTTP/TLS 連線、憑證處理）

  • 低階系統操作 （遙測、通訊端連線）

  • AWS 服務端點解析和連線集區

  • 基礎設施元件的詳細偵錯資訊

qchat.log - 聊天應用程式特定的日誌，包括：

  • 聊天應用程式錯誤和狀態處理問題

  • MCP （模型內容通訊協定） 伺服器管理和連線錯誤

  • 應用程式層級遷移問題

  • 使用者互動中斷和聊天處理失敗

  • 更高層級的應用程式邏輯錯誤

mcp.log - 模型內容通訊協定伺服器日誌 （使用 MCP 伺服器時填入）
translate.log - 自然語言到 shell 轉譯日誌 （使用轉譯功能時填入）

日誌檔案之間的主要差異

範圍和細節差異：

  • chat.log：涵蓋整個 Q CLI 基礎設施的全方位系統層級記錄

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

內容焦點差異：

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

  • 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 開發套件操作和服務呼叫

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

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

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

一般分析秘訣：

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

  • 錯誤模式 - 尋找重複的錯誤或錯誤層疊

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

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

提示

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

常見的日誌模式和解決方案

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

MCP 伺服器連線錯誤

日誌模式 (qchat.log)：「用戶端的背景接聽執行緒 【server-name】：RecvError（關閉）」或「傳輸層的所有寄件者捨棄」

解決方案：MCP 伺服器程序已停止執行。這通常是結束 Amazon Q CLI 或伺服器正常關閉時的預期行為。

聊天處理中斷

日誌模式 (qchat.log)：「處理目前狀態 err=中斷 { tool_uses： None } 時發生錯誤」

解決方案：當使用者取消聊天操作 （例如 Ctrl+C) 且為預期行為時，就會發生這種情況。

遙測驗證錯誤

日誌模式 (qchat.log)：「無法傳送 cw 遙測事件 err=ValidationError 【ValidationException】：格式不正確的請求」

解決方案：這些通常是不會影響核心功能的非關鍵遙測傳輸問題。

遷移警告

日誌模式 （在 qchat.log 中）：「遷移未發生，原因如下：中止遷移」

解決方案：這通常是與組態遷移相關的非關鍵警告，通常可以忽略。

身分驗證失敗

日誌模式 （在 chat.log 中）：AWS 開發套件操作中的身分驗證相關錯誤

解決方案：執行 q login以重新驗證或檢查您的 AWS 登入資料

網路連線問題

日誌模式 （在 chat.log 中）：「連線逾時」、「網路無法連線」或失敗的 HTTP 連線

解決方案：檢查您的網際網路連線和防火牆設定

AWS 開發套件操作失敗

日誌模式 （在 chat.log 中）：Cognito Identity 操作失敗或憑證擷取錯誤

解決方案：檢查您的 AWS 登入資料和網路連線。可能需要重新驗證

取得日誌分析的協助

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

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

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