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á.
Acessando e usando os registros do Amazon Q Developer
O Amazon Q Developer gera registros detalhados que podem ajudar você a diagnosticar e resolver problemas. Este guia mostra como acessar registros de diferentes interfaces do Amazon Q e configurar os níveis de registro para obter as informações de que você precisa para solucionar problemas.
Navegação rápida:
Visão geral do acesso aos registros
Há duas formas principais de acessar os registros do Amazon Q Developer, dependendo de como você está usando o serviço:
-
Extensões IDE - VS Code e JetBrains IDEs tem um botão “Mostrar registros” para acessar registros específicos do Amazon Q
-
Interface de linha de comando (Amazon Q CLI) - Os registros 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, nomes de contas e IDs recursos. Tenha cuidado ao compartilhar arquivos de log com outras pessoas.
Registros de extensão do IDE
Acessando registros por meio da interface do IDE
-
Abra o painel de bate-papo do Amazon Q em seu IDE (VS Code ou JetBrains)
-
Clique no botão Mostrar registros no canto superior direito do painel de bate-papo
-
Reconheça o aviso de sensibilidade que aparece
-
O local do arquivo de log será aberto no gerenciador de arquivos do seu sistema para análise
Analisando registros de extensão do IDE
Ao revisar os registros de extensão do IDE, procure:
-
Mensagens de erro - Linhas contendo “ERRO” ou “FATAL” indicam problemas críticos
-
Problemas de autenticação - Procure erros relacionados à autenticação ou às credenciais
-
Conectividade de rede - Tempos limite de conexão ou erros relacionados à rede
-
Erros específicos de recursos - Problemas relacionados a sugestões de código, bate-papo ou outros recursos específicos
Registros da Amazon Q CLI
O Amazon Q CLI gera automaticamente registros abrangentes para todas as operações, independentemente das configurações de verbosidade. Os registros são sempre gravados em arquivos, enquanto os sinalizadores de verbosidade controlam apenas o que aparece na saída do terminal.
Localizações e arquivos de log do Amazon Q CLI
Os registros do Amazon Q CLI são armazenados automaticamente nos seguintes locais:
| Sistema operacional | Localização do registro |
|---|---|
| macOS | $TMPDIR/qlog/(normalmente/var/folders/.../qlog/) |
| Linux/WSL | $XDG_RUNTIME_DIR/qlog/ ou $TMPDIR/qlog/ ou /tmp/qlog/ |
| Windows | %TEMP%\qlog\ |
A Amazon Q CLI cria automaticamente vários arquivos de log especializados:
chat.log- Principais registros de wrapper do Amazon Q CLI, incluindo:-
Operações de inicialização e inicialização do Amazon Q CLI
Chamadas do AWS SDK (Identidade Cognito, fluxos de autenticação)
Operações de rede (conexões HTTP/TLS, tratamento de certificados)
Operações de sistema de baixo nível (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- Registros específicos do aplicativo de bate-papo, incluindo:-
Erros do aplicativo de bate-papo e problemas de processamento de estado
Erros de gerenciamento e conexão do servidor MCP (Model Context Protocol)
Problemas de migração em nível de aplicativo
Interrupções na interação do usuário e falhas no processamento do bate-papo
Erros lógicos de aplicativos de alto nível
mcp.log- Registros do servidor do Model Context Protocol (preenchidos ao usar servidores MCP)translate.log- Linguagem natural para registros de tradução do shell (preenchida ao usar o recurso de tradução)
Principais diferenças entre arquivos de log
Diferenças de escopo e detalhes:
chat.log: Registro abrangente em nível de sistema cobrindo toda a infraestrutura do Q CLIqchat.log: Registro focado em nível de aplicativo específico para a funcionalidade de bate-papo
Diferenças no foco do conteúdo:
chat.log: componentes internos do AWS SDK, protocolos de rede, fluxos de autenticação, operações do sistemaqchat.log: lógica de bate-papo, ciclo de vida do servidor MCP, problemas de experiência do usuário, erros de aplicativos
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 quando você usa a CLI pela primeira vez, mesmo sem sinalizadores detalhados.
Fluxo de trabalho de solução de problemas do Amazon Q CLI
Siga essa abordagem para coletar informações de diagnóstico dos registros.
-
Identifique o diretório de log do seu sistema:
No Linux/WSL:
echo $XDG_RUNTIME_DIR/qlog/No macOS:
echo $TMPDIR/qlog/No Windows:
echo %TEMP%\qlog\ -
Execute o comando Amazon Q CLI com o máximo de detalhamento para ver a saída detalhada em seu terminal:
q -vvv chat -
Reproduza o problema que você está enfrentando
-
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:
No macOS/Linux:
less -r $XDG_RUNTIME_DIR/qlog/qchat.log less -r $XDG_RUNTIME_DIR/qlog/chat.logAlternativa no macOS:
less -r $TMPDIR/qlog/qchat.log less -r $TMPDIR/qlog/chat.logNo Windows:
type %TEMP%\qlog\qchat.log type %TEMP%\qlog\chat.log -
Para monitoramento de registros em tempo real durante a solução de problemas, use:
Monitore todos os arquivos de log simultaneamente:
tail -f $XDG_RUNTIME_DIR/qlog/*.logMonitore arquivos específicos:
tail -f $XDG_RUNTIME_DIR/qlog/qchat.logtail -f $XDG_RUNTIME_DIR/qlog/chat.log
Analisando os registros da CLI do Amazon Q
Os logs do Amazon Q CLI usam níveis de registro padrão para categorizar as informações por importância:
- ERRO
Problemas críticos que impedem a operação normal - comece aqui ao solucionar problemas
- WARN
Problemas potenciais que não impedem a funcionalidade, mas devem ser observados
- INFO
Mensagens operacionais gerais sobre o que o aplicativo está fazendo
- DEBUG
Informações técnicas detalhadas úteis para uma investigação mais profunda
Ao examinar os registros do Amazon Q CLI, concentre-se nessas áreas principais nos diferentes arquivos de log:
qchat.loganálise - problemas no nível do aplicativo, incluindo:-
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
chat.loganálise - Detalhes operacionais do tempo de execução, incluindo:-
DEBUG q_cli: :cli - Execução e inicialização de comandos do Amazon Q CLI
DEBUG aws_sdk_* - Operações e chamadas de serviço do AWS SDK
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 registro com o momento em que os problemas ocorreram
-
Padrões de erro - Procure erros repetidos ou cascatas de erros
-
Solicitação IDs - 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 grepawk, ou editores de texto com funcionalidade de pesquisa para filtrar registros de mensagens de erro ou padrões específicos. Por exemplo: grep -i error $XDG_RUNTIME_DIR/qlog/*.log
Padrões e soluções de registro comuns
Aqui estão alguns problemas comuns que você pode encontrar nos registros e suas soluções típicas:
- Erros de conexão do 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 no processamento do chat
-
Padrão de registro (em qchat.log): “Ocorreu um erro ao processar o estado atual ERR=interrupted {tool_uses: None}”
Solução: Isso ocorre quando as operações de bate-papo 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 registro (em qchat.log): “A migração não aconteceu pelo seguinte motivo: Abortar a migração”
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): erros relacionados à autenticação 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 registro (em chat.log): “Tempo limite de conexão”, “Rede inacessível” ou conexões HTTP com falha
Solução: verifique sua conexão com a Internet e as configurações de firewall
- Falhas na operação do AWS SDK
-
Padrão de registro (em chat.log): falhas nas operações de Identidade Cognito ou erros de recuperação de credenciais
Solução: verifique suas credenciais e conectividade de rede da AWS. Pode exigir reautenticação
Obter ajuda com a análise de registros
Se você precisar de ajuda para analisar registros ou resolver problemas:
-
Ao entrar em contato com o suporte, inclua trechos de registro relevantes (com informações confidenciais removidas)
-
Forneça contexto sobre quando o problema ocorre e as etapas para reproduzi-lo
