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
Há duas formas principais de acessar os logs 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 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, nomes de contas e IDs 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
-
Abra o painel de bate-papo do Amazon Q em seu IDE (VS Code ou JetBrains)
-
Clique no botão Mostrar logs no canto superior direito do painel de chat
-
Confirme o recebimento do aviso exibido sobre confidencialidade
-
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
-
Erros específicos de recursos: problemas relacionados a sugestões de código, chat 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 (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: 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)
Problemas de migração no nível de aplicações
Interrupções na interação do usuário e falhas no processamento do chat
Erros de lógica de aplicações de nível superior
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 Qqchat.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 sistemaqchat.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.
-
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 da CLI do Amazon Q 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 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/*.logPara monitorar arquivos específicos:
tail -f $XDG_RUNTIME_DIR/qlog/qchat.logtail -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:
- ERRO
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:
- Análise de
qchat.log: problemas no nível da aplicação, 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
- 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
-
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 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): erros relacionados à autenticação nas operações do SDK da AWS
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
