本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
访问和使用 Amazon Q 开发者版日志
Amazon Q 开发者版会生成详细的日志，有助于您诊断和解决问题。本指南向您展示如何访问不同 Amazon Q 接口的日志，以及如何配置日志记录级别以获取进行故障排除所需的信息。
快速导航：
日志访问概述
访问 Amazon Q 开发者版日志的主要方式有两种，具体取决于您使用服务的方式：
-
IDE 扩展程序-VS Code 并 JetBrains IDEs 有一个 “显示日志” 按钮用于访问 Amazon Q 的特定日志
-
命令行界面（Amazon Q CLI）：日志本地存储在临时目录中，详细级别可配置
重要
日志文件可能包含您与 Amazon Q 的对话和互动中的敏感信息，包括文件路径、代码片段、命令输出 IDs、账户和资源名称。与他人共享日志文件时，请务必小心。
IDE 扩展日志
通过 IDE 接口访问日志
-
在你的 IDE 中打开 Amazon Q 聊天面板（VS Code 或 JetBrains）
-
点击聊天面板右上角的显示日志按钮
-
确认出现的敏感性警告
-
日志文件位置将在系统的文件管理器中打开以供查看
分析 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 身份、身份验证流程）
网络操作（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 故障排除工作流程
按照此方法从日志中收集诊断信息。
-
确定系统的日志目录：
在 Linux/WSL 上：
echo $XDG_RUNTIME_DIR/qlog/在 macOS 上：
echo $TMPDIR/qlog/在 Windows 上：
echo %TEMP%\qlog\ -
以最大详细程度运行 Amazon Q CLI 命令以查看终端中的详细输出：
q -vvv chat -
重现您遇到的问题
-
退出 Amazon Q CLI 并检查相关的日志文件。对于大多数问题，请检查两个主日志文件：
在 macOS/Linux 上：
less -r $XDG_RUNTIME_DIR/qlog/qchat.log less -r $XDG_RUNTIME_DIR/qlog/chat.logmacOS 上的替代日志文件：
less -r $TMPDIR/qlog/qchat.log less -r $TMPDIR/qlog/chat.log在 Windows 上：
type %TEMP%\qlog\qchat.log type %TEMP%\qlog\chat.log -
要在故障排除期间进行实时日志监控，请使用：
同时监控所有日志文件：
tail -f $XDG_RUNTIME_DIR/qlog/*.log监控特定文件：
tail -f $XDG_RUNTIME_DIR/qlog/qchat.logtail -f $XDG_RUNTIME_DIR/qlog/chat.log
分析 Amazon Q CLI 日志
Amazon Q CLI 日志使用标准日志记录级别按重要性对信息进行分类：
- ERROR
妨碍正常操作的关键问题：故障排除时从这里开始
- 警告
不会停止功能但应引起注意的潜在问题
- INFO
有关应用程序正在执行的操作的一般操作消息
- 调试
有助于进行更深入调查的详细的技术信息
检查 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：系统遥测和套接字连接问题
一般分析提示：
-
时间戳：将日志条目与问题发生的时间相关联
-
错误模式：查找重复的错误或错误级联
-
请求 IDs-跟踪特定的 API 调用及其结果
-
连接状态：监控网络连接和身份验证状态
提示
使用诸如 grep、awk 或具有搜索功能的文本编辑器之类的工具来筛选日志，以查找特定的错误消息或模式。例如：grep -i error $XDG_RUNTIME_DIR/qlog/*.log
常见日志模式和解决方案
以下是在日志中可能会发现的一些常见问题及其典型解决方案：
- MCP 服务器连接错误
-
日志模式（在 qchat.log 中）：“客户端 [服务器名] 的后台监听线程： RecvError（已关闭）” 或 “传输层的所有发件人都已删除”
解决方案：MCP 服务器进程已停止运行。这通常是退出 Amazon Q CLI 或服务器正常关闭时的预期行为。
- 聊天处理中断
-
日志模式（在 qchat.log 中）：“An error occurred processing the current state err=Interrupted { tool_uses: None }”
解决方案：当用户取消聊天操作（例如，Ctrl+C）就会发生这种情况，是预期行为。
- 遥测验证错误
-
日志模式（在 qchat.log 中）：“无法发送 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 中）：“Connection timeout”、“Network unreachable”或 HTTP 连接失败
解决方案：请检查您的网络连接和防火墙设置。
- AWS SDK 操作失败
-
日志模式（在 chat.log 中）：Cognito 身份操作失败或凭证检索错误
解决方案：检查您的 AWS 凭证和网络连接。可能需要重新进行身份验证
获得有关日志分析的帮助
如果您在分析日志或解决问题时需要协助：
-
联系支持人员时，请附上相关的日志摘录（移除敏感信息）
-
提供有关问题何时发生以及重现问题的步骤的上下文
