本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 访问和使用 Amazon Q 开发者版日志
<a name="troubleshooting-q-logs"></a>

Amazon Q 开发者版会生成详细的日志，有助于您诊断和解决问题。本指南向您展示如何访问不同 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 开发者版日志的主要方式有两种，具体取决于您使用服务的方式：
+ **IDE 扩展程序**-VS Code 并 JetBrains IDEs 有一个 “显示日志” 按钮用于访问 Amazon Q 的特定日志
+ **命令行界面（Amazon Q CLI）**：日志本地存储在临时目录中，详细级别可配置

**重要**  
日志文件可能包含您与 Amazon Q 的对话和互动中的敏感信息，包括文件路径、代码片段、命令输出 IDs、账户和资源名称。与他人共享日志文件时，请务必小心。

## 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 身份、身份验证流程）
+ 网络操作（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  
妨碍正常操作的关键问题：故障排除时从这里开始

警告  
不会停止功能但应引起注意的潜在问题

INFO  
有关应用程序正在执行的操作的一般操作消息

调试  
有助于进行更深入调查的详细的技术信息

检查 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**：系统遥测和套接字连接问题

一般分析提示：
+ **时间戳**：将日志条目与问题发生的时间相关联
+ **错误模式**：查找重复的错误或错误级联
+ **请求 IDs**-跟踪特定的 API 调用及其结果
+ **连接状态**：监控网络连接和身份验证状态

**提示**  
使用诸如 **grep**、**awk** 或具有搜索功能的文本编辑器之类的工具来筛选日志，以查找特定的错误消息或模式。例如：**grep -i error \$1XDG\$1RUNTIME\$1DIR/qlog/\$1.log**

## 常见日志模式和解决方案
<a name="common-log-patterns"></a>

以下是在日志中可能会发现的一些常见问题及其典型解决方案：

MCP 服务器连接错误  
**日志模式（在 qchat.log 中）：**“客户端 [服务器名] 的后台监听线程： RecvError（已关闭）” 或 “传输层的所有发件人都已删除”  
**解决方案：**MCP 服务器进程已停止运行。这通常是退出 Amazon Q CLI 或服务器正常关闭时的预期行为。

聊天处理中断  
**日志模式（在 qchat.log 中）：**“An error occurred processing the current state err=Interrupted \$1 tool\$1uses: None \$1”  
**解决方案：**当用户取消聊天操作（例如，Ctrl\$1C）就会发生这种情况，是预期行为。

遥测验证错误  
**日志模式（在 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 凭证和网络连接。可能需要重新进行身份验证

## 获得有关日志分析的帮助
<a name="getting-help-with-logs"></a>

如果您在分析日志或解决问题时需要协助：
+ 联系支持人员时，请附上相关的日志摘录（移除敏感信息）
+ 提供有关问题何时发生以及重现问题的步骤的上下文