As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Acessar e usar os logs do Amazon Q Developer
O Amazon Q Developer gera logs detalhados que podem ajudar você a diagnosticar e resolver problemas. Este guia mostra como acessar logs de diferentes interfaces do Amazon Q e configurar os níveis de registro em log para obter as informações necessárias para solucionar problemas.
**Navegação rápida:**
+ [Visão geral do acesso aos logs](#log-access-overview)
+ [Logs de extensão do IDE](#ide-logs)
+ [Logs da CLI do Amazon Q](#cli-logs)
+ [Padrões e soluções comuns de logs](#common-log-patterns)
+ [Obter ajuda com a análise de logs](#getting-help-with-logs)
## Visão geral do acesso aos logs
Há duas formas principais de acessar os logs do Amazon Q Developer, dependendo de como você está usando o serviço:
+ **Extensões do IDE** - O VS Code e os JetBrains IDEs têm um botão “Mostrar registros” para acessar registros específicos do Amazon Q
+ **Interface de linha de comandos (CLI do Amazon Q)**: os logs são armazenados localmente em diretórios temporários com níveis de detalhes configuráveis
**Importante**
Os arquivos de log podem conter informações confidenciais de suas conversas e interações com o Amazon Q, incluindo caminhos de arquivos, trechos de código, saídas de comandos, IDs de contas e nomes de recursos. Tenha cuidado ao compartilhar arquivos de log com outras pessoas.
## Logs de extensão do IDE
### Acessar logs por meio da interface do IDE
1. Abra o painel de bate-papo do Amazon Q em seu IDE (VS Code ou JetBrains)
1. Clique no botão **Mostrar logs** no canto superior direito do painel de chat
1. Confirme o recebimento do aviso exibido sobre confidencialidade
1. O local do arquivo de log será aberto no gerenciador de arquivos do seu sistema para revisão
### Analisar logs de extensão do IDE
Ao revisar os logs de extensão do IDE, procure:
+ **Mensagens de erro**: linhas que contém “ERRO” ou “FATAL” indicam problemas críticos
+ **Problemas de autenticação**: busque por erros relacionados a autenticação ou credenciais
+ **Conectividade de rede**: tempos limite de conexão ou erros relacionados à rede
+ **Feature-specific erros** - Problemas relacionados a sugestões de código, bate-papo ou outros recursos específicos
## Logs da CLI do Amazon Q
A CLI do Amazon Q automaticamente gera logs abrangentes para todas as operações, independentemente das configurações de detalhamento. Os logs são sempre gravados em arquivos, enquanto os sinalizadores de detalhamento controlam somente o que aparece na saída do terminal.
### Localizações e arquivos de log da CLI do Amazon Q
Os logs da CLI do Amazon Q são armazenados automaticamente nos seguintes locais:
| Sistema operacional | Locais de log |
| --- | --- |
| macOS | $TMPDIR/qlog/ (normalmente /var/folders/.../qlog/) |
| Linux/WSL | $XDG\_RUNTIME\_DIR/qlog/ ou $TMPDIR/qlog/ ou /tmp/qlog/ |
| Windows | %TEMP%\\qlog\\ |
A CLI do Amazon Q automaticamente cria vários arquivos de log especializados:
`chat.log`: **principais logs de wrapper da CLI do Amazon Q**, incluindo:
+ Operações de inicialização da CLI do Amazon Q
+ Chamadas do SDK da AWS (Cognito Identity, fluxos de autenticação)
+ Operações de rede (HTTP/TLS conexões, tratamento de certificados)
+ Low-level operações do sistema (telemetria, conexões de soquete)
+ Resolução de endpoints de serviços da AWS e pool de conexões
+ Informações detalhadas de depuração para componentes de infraestrutura
`qchat.log`: **logs específicos da aplicação de chat**, incluindo:
+ Erros da aplicação de chat e problemas de processamento de estado
+ Erros de gerenciamento e conexão do servidor MCP (protocolo de contexto para modelos)
+ Application-level problemas de migração
+ Interrupções na interação do usuário e falhas no processamento do chat
+ Higher-level erros de lógica do aplicativo
`mcp.log`: logs do servidor do protocolo de contexto para modelos (preenchidos ao usar servidores MCP)
`translate.log`: linguagem natural para logs de tradução do shell (preenchidos ao usar o recurso de tradução)
#### Principais diferenças entre arquivos de log
**Diferenças de escopo e detalhes:**
+ `chat.log`: registro em log abrangente no nível do sistema, cobrindo toda a infraestrutura da CLI do Q
+ `qchat.log`: registro em log focado no nível da aplicação específica da funcionalidade de chat
**Diferenças no foco do conteúdo:**
+ `chat.log`: componentes internos do SDK da AWS, protocolos de rede, fluxos de autenticação, operações do sistema
+ `qchat.log`: lógica de chat, ciclo de vida do servidor MCP, problemas de experiência do usuário, erros de aplicações
**nota**
Os arquivos de log são armazenados somente em sua máquina local e não são enviados para AWS o. Todos os arquivos de log são criados automaticamente no primeiro uso da CLI, mesmo sem sinalizadores detalhados.
### Fluxo de trabalho de solução de problemas da CLI do Amazon Q
Siga essa abordagem para coletar informações de diagnóstico dos logs.
1. Identifique o diretório de log do seu sistema:
Em Linux/WSL:
```
echo $XDG_RUNTIME_DIR/qlog/
```
No macOS:
```
echo $TMPDIR/qlog/
```
No Windows:
```
echo %TEMP%\qlog\
```
1. Execute o comando da CLI do Amazon Q com o máximo de detalhamento para ver a saída detalhada em seu terminal:
```
q -vvv chat
```
1. Reproduza o problema que você está enfrentando
1. Saia da CLI do Amazon Q e examine os arquivos de log relevantes. Para a maioria dos problemas, verifique os dois arquivos de log principais:
Em macOS/Linux:
```
less -r $XDG_RUNTIME_DIR/qlog/qchat.log
less -r $XDG_RUNTIME_DIR/qlog/chat.log
```
Alternativa no macOS:
```
less -r $TMPDIR/qlog/qchat.log
less -r $TMPDIR/qlog/chat.log
```
No Windows:
```
type %TEMP%\qlog\qchat.log
type %TEMP%\qlog\chat.log
```
1. Para o monitoramento em tempo real de logs durante a solução de problemas, use:
Para monitorar todos os arquivos de log simultaneamente:
```
tail -f $XDG_RUNTIME_DIR/qlog/*.log
```
Para monitorar arquivos específicos:
```
tail -f $XDG_RUNTIME_DIR/qlog/qchat.log
```
```
tail -f $XDG_RUNTIME_DIR/qlog/chat.log
```
### Analisar os logs da CLI do Amazon Q
Os logs da CLI do Amazon Q usam níveis de registro em log padrão para categorizar as informações por importância:
ERROR
Problemas críticos que impedem a operação normal (comece a solução de problemas por aqui)
WARN
Problemas potenciais que não interrompem a funcionalidade, mas devem ser observados
INFO
Mensagens operacionais gerais sobre a operação da aplicação
DEBUG
Informações técnicas detalhadas úteis para uma investigação mais profunda
Ao examinar os logs da CLI do Amazon Q, concentre-se nessas áreas principais nos diferentes arquivos de log:
`qchat.log`análise - Application-level questões que incluem:
+ **ERRO chat\_cli::cli::chat**: erros de processamento e gerenciamento de estado do chat
+ **ERRO chat\_cli::cli::agent**: problemas de migração e relacionados ao agente
+ **ERRO chat\_cli::telemetry**: falhas na validação e transmissão da telemetria
Análise de `chat.log`: detalhes operacionais do runtime, incluindo:
+ **DEBUG q\_cli::cli**: execução e inicialização do comando da CLI do Amazon Q
+ **DEBUG aws\_sdk\_\***: operações e chamadas de serviço do SDK da AWS
+ **DEBUG rustls: :\*** - estabelecimento de TLS/SSL conexão e tratamento de certificados
+ **DEBUG hyper\_\***: gerenciamento de conexões HTTP e operações de rede
+ **ERRO fig\_telemetry**: problemas de telemetria do sistema e conexão de soquete
Dicas gerais de análise:
+ **Carimbos de data e hora**: correlacione as entradas de log com o momento em que os problemas ocorreram
+ **Padrões de erro**: procure erros repetidos ou cascatas de erros
+ **IDs de solicitação**: acompanhe chamadas de API específicas e seus resultados
+ **Estados de conexão**: monitore a conectividade da rede e o status de autenticação
**dica**
Use ferramentas como **grep**, **awk** ou editores de texto com funcionalidade de pesquisa para filtrar logs de mensagens de erro ou padrões específicos. Por exemplo: **grep -i error $XDG\_RUNTIME\_DIR/qlog/\*.log**
## Padrões e soluções comuns de logs
Confira os seguintes alguns problemas comuns que podem ocorrer em logs e suas soluções típicas:
Erros de conexão com o servidor MCP
**Padrão de registro (em qchat.log):** “Tópico de escuta em segundo plano para o cliente [nome do servidor]: RecvError (Fechado)” ou “Todos os remetentes foram descartados para a camada de transporte”
**Solução:** os processos do servidor MCP pararam de ser executados. Normalmente, esse é o comportamento esperado ao sair da CLI do Amazon Q ou quando os servidores são desligados normalmente.
Interrupções do processamento de chat
**Log pattern (in qchat.log):** “An error occurred processing the current state err=Interrupted { tool\_uses: None }”
**Solução:** isso ocorre quando as operações de chat são canceladas pelo usuário (por exemplo, Ctrl\+C) e é o comportamento esperado.
Erros de validação de telemetria
**Padrão de registro (em qchat.log):** “Falha ao enviar o evento de telemetria cw err= ValidationError [ValidationException]: Solicitação formada incorretamente”
**Solução:** normalmente, esses são problemas de transmissão de telemetria não críticos que não afetam a funcionalidade principal.
Avisos de migração
**Padrão de log (em qchat.log):** “Migration did not happen for the following reason: Aborting migration”
**Solução:** normalmente, esse é um aviso não crítico relacionado à migração da configuração e geralmente pode ser ignorado.
Falhas de autenticação
**Padrão de log (em chat.log):** Authentication-related erros nas operações do AWS SDK
**Solução:** execute **q login** para reautenticar ou verificar suas credenciais da AWS
Problemas de conectividade de rede
**Padrão de log (em chat.log):** “Tempo limite de conexão”, “Rede inacessível” ou conexões HTTP com falha
**Solução:** verifique suas configurações de conexão com a internet e firewall
Falhas na operação do SDK da AWS
**Padrão de log (em qchat.log):** Failed Cognito Identity operations or credential retrieval errors
**Solução:** verifique suas credenciais da AWS e conectividade de rede. Pode exigir reautenticação
## Obter ajuda com a análise de logs
Se você precisar de ajuda para analisar logs ou resolver problemas:
+ Ao entrar em contato com o suporte, inclua trechos de logs relevantes (remova as informações confidenciais)
+ Forneça contexto sobre quando o problema ocorre e as etapas para reproduzi-lo