Accès et utilisation des journaux des développeurs Amazon Q

Amazon Q Developer génère des journaux détaillés qui peuvent vous aider à diagnostiquer et à résoudre les problèmes. Ce guide explique comment accéder aux journaux des différentes interfaces Amazon Q et comment configurer les niveaux de journalisation pour obtenir les informations dont vous avez besoin pour résoudre les problèmes.

Navigation rapide :

• Présentation de l'accès aux journaux

• Journaux des extensions IDE

• Journaux de la CLI Amazon Q

• Modèles et solutions de journalisation courants

• Obtenir de l'aide pour l'analyse des journaux

Vue d'ensemble des accès aux journaux

Il existe deux méthodes principales pour accéder aux journaux des développeurs Amazon Q, selon la manière dont vous utilisez le service :

• Extensions IDE : code VS et JetBrains IDEs bouton « Afficher les journaux » pour accéder aux journaux spécifiques à Amazon Q

• Interface de ligne de commande (Amazon Q CLI) : les journaux sont stockés localement dans des répertoires temporaires avec des niveaux de détail configurables

Important

Les fichiers journaux peuvent contenir des informations sensibles issues de vos conversations et interactions avec Amazon Q, notamment des chemins de fichiers, des extraits de code, des sorties de commande, des noms de comptes IDs et de ressources. Faites preuve de prudence lorsque vous partagez des fichiers journaux avec d'autres personnes.

Journaux des extensions IDE

Accès aux journaux via l'interface IDE

1. Ouvrez le panneau de discussion Amazon Q dans votre IDE (VS Code ou JetBrains)

2. Cliquez sur le bouton Afficher les journaux dans le coin supérieur droit du panneau de discussion

3. Reconnaissez l'avertissement de sensibilité qui s'affiche

4. L'emplacement du fichier journal s'ouvrira dans le gestionnaire de fichiers de votre système pour examen

Analyse des journaux des extensions IDE

Lorsque vous consultez les journaux des extensions IDE, recherchez :

• Messages d'erreur - Les lignes contenant « ERROR » ou « FATAL » indiquent des problèmes critiques

• Problèmes d'authentification : recherchez les erreurs liées à l'authentification ou aux informations d'identification

• Connectivité réseau : délais de connexion ou erreurs liées au réseau

• Erreurs spécifiques aux fonctionnalités : problèmes liés aux suggestions de code, au chat ou à d'autres fonctionnalités spécifiques

Journaux de la CLI Amazon Q

L'Amazon Q CLI génère automatiquement des journaux complets pour toutes les opérations, quels que soient les paramètres de verbosité. Les journaux sont toujours écrits dans des fichiers, tandis que les indicateurs de verbosité contrôlent uniquement ce qui apparaît dans la sortie du terminal.

Emplacements et fichiers des journaux de la CLI Amazon Q

Les journaux de la CLI Amazon Q sont automatiquement stockés aux emplacements suivants :

Système d'exploitation	Emplacement du journal
macOS	$TMPDIR/qlog/(généralement/var/folders/.../qlog/)
Linux/WSL	$XDG_RUNTIME_DIR/qlog/ ou $TMPDIR/qlog/ ou /tmp/qlog/
Windows	%TEMP%\qlog\

La CLI Amazon Q crée automatiquement plusieurs fichiers journaux spécialisés :

chat.log- Principaux journaux du wrapper Amazon Q CLI, notamment :

• Initialisation et opérations de démarrage de la CLI Amazon Q

• Appels du SDK AWS (Cognito Identity, flux d'authentification)

• Opérations réseau (connexions HTTP/TLS, gestion des certificats)

• Opérations système de bas niveau (télémétrie, connexions par socket)

• Résolution des points de terminaison des services AWS et regroupement des connexions

• Informations de débogage détaillées pour les composants de l'infrastructure

qchat.log- Des journaux spécifiques à l'application de chat, notamment :

• Erreurs d'application de chat et problèmes de traitement des états

• Gestion du serveur MCP (Model Context Protocol) et erreurs de connexion

• Problèmes de migration au niveau de l'application

• Interruptions des interactions avec les utilisateurs et échecs du traitement du chat

• Erreurs de logique d'application de niveau supérieur

mcp.log- Journaux du serveur Model Context Protocol (remplis lors de l'utilisation de serveurs MCP)

translate.log- Journaux de traduction du langage naturel vers le shell (remplis lors de l'utilisation de la fonction de traduction)

Principales différences entre les fichiers journaux

Différences de portée et de détail :

• chat.log: journalisation complète au niveau du système couvrant l'ensemble de l'infrastructure Q CLI

• qchat.log: journalisation ciblée au niveau de l'application spécifique aux fonctionnalités de chat

Différences de focalisation sur le contenu :

• chat.log: composants internes du SDK AWS, protocoles réseau, flux d'authentification, opérations du système

• qchat.log: logique du chat, cycle de vie du serveur MCP, problèmes d'expérience utilisateur, erreurs d'application

Note

Les fichiers journaux sont stockés uniquement sur votre ordinateur local et ne sont pas envoyés à AWS. Tous les fichiers journaux sont créés automatiquement lorsque vous utilisez la CLI pour la première fois, même sans indicateurs détaillés.

Flux de travail de dépannage de la CLI Amazon Q

Suivez cette approche pour recueillir des informations de diagnostic à partir des journaux.

1. Identifiez le répertoire des journaux de votre système :

   Sous Linux/WSL :

   echo $XDG_RUNTIME_DIR/qlog/

   Sur macOS :

   echo $TMPDIR/qlog/

   Sous Windows :

   echo %TEMP%\qlog\

2. Exécutez la commande Amazon Q CLI avec un maximum de verbosité pour afficher le résultat détaillé dans votre terminal :

   q -vvv chat

3. Reproduisez le problème que vous rencontrez

4. Quittez l'interface de ligne de commande Amazon Q et examinez les fichiers journaux pertinents. Pour la plupart des problèmes, consultez les deux principaux fichiers journaux :

   Sur macOS/Linux :

   less -r $XDG_RUNTIME_DIR/qlog/qchat.log
   less -r $XDG_RUNTIME_DIR/qlog/chat.log

   Alternative sur macOS :

   less -r $TMPDIR/qlog/qchat.log
   less -r $TMPDIR/qlog/chat.log

   Sous Windows :

   type %TEMP%\qlog\qchat.log
   type %TEMP%\qlog\chat.log

5. Pour surveiller les journaux en temps réel lors du dépannage, utilisez :

   Surveillez tous les fichiers journaux simultanément :

   tail -f $XDG_RUNTIME_DIR/qlog/*.log

   Surveillez des fichiers spécifiques :

   tail -f $XDG_RUNTIME_DIR/qlog/qchat.log

   tail -f $XDG_RUNTIME_DIR/qlog/chat.log

Analyse des journaux de la CLI Amazon Q

Les journaux de la CLI Amazon Q utilisent des niveaux de journalisation standard pour classer les informations par ordre d'importance :

ERROR

Problèmes critiques qui empêchent le fonctionnement normal : commencez ici lors du dépannage

WARN

Problèmes potentiels qui n'interrompent pas le fonctionnement, mais qui doivent être pris en compte

INFO

Messages opérationnels généraux concernant le fonctionnement de l'application

DEBUG

Informations techniques détaillées utiles pour une enquête plus approfondie

Lorsque vous examinez les journaux de la CLI Amazon Q, concentrez-vous sur les domaines clés suivants dans les différents fichiers journaux :

qchat.loganalyse - Problèmes au niveau de l'application, notamment :

• ERREUR chat_cli : :cli : :chat - Erreurs liées au traitement du chat et à la gestion des états

• ERREUR chat_cli : :cli : :agent - Problèmes liés à la migration et à l'agent

• ERREUR chat_cli : :telemetry - Validation de la télémétrie et échecs de transmission

chat.loganalyse - Détails opérationnels de l'exécution, notamment :

• DEBUG q_cli : :cli - Exécution et initialisation de la commande Amazon Q CLI

• DEBUG aws_sdk_* - Opérations du SDK AWS et appels de service

• DEBUG rustls : :* - établissement de la TLS/SSL connexion et gestion des certificats

• DEBUG hyper_* - Gestion des connexions HTTP et opérations réseau

• ERREUR fig_telemetry - Problèmes de télémétrie du système et de connexion au socket

Conseils d'analyse généraux :

• Horodatages - Corrélez les entrées du journal avec le moment où les problèmes sont survenus

• Modèles d'erreurs : recherchez les erreurs répétées ou les cascades d'erreurs

• Demande IDs - Suivez des appels d'API spécifiques et leurs résultats

• États de connexion - Surveillez la connectivité réseau et l'état de l'authentification

Astuce

Utilisez des outils tels que grepawk, ou des éditeurs de texte dotés d'une fonctionnalité de recherche pour filtrer les journaux afin de détecter des messages ou des modèles d'erreur spécifiques. Par exemple : grep -i error $XDG_RUNTIME_DIR/qlog/*.log

Modèles et solutions de journalisation courants

Voici quelques problèmes courants que vous pouvez rencontrer dans les journaux et leurs solutions typiques :

Erreurs de connexion au serveur MCP

Modèle de journal (dans qchat.log) : « Fil d'écoute en arrière-plan pour le client [nom du serveur] : RecvError (fermé) » ou « Tous les expéditeurs ont été supprimés pour la couche de transport »

Solution : les processus du serveur MCP ont cessé de fonctionner. Ce comportement est généralement attendu lorsque vous quittez l'interface de ligne de commande Amazon Q ou lorsque les serveurs s'arrêtent normalement.

Interruptions du traitement du chat

Modèle de journal (dans qchat.log) : « Une erreur s'est produite lors du traitement de l'état actuel ERR=Interrupted {tool_uses : None} »

Solution : Cela se produit lorsque les opérations de chat sont annulées par l'utilisateur (par exemple, Ctrl+C) et c'est un comportement attendu.

Erreurs de validation de télémétrie

Modèle de journal (dans qchat.log) : « Impossible d'envoyer l'événement de télémétrie cw err= ValidationError [ValidationException] : demande mal formée »

Solution : Il s'agit généralement de problèmes de transmission de télémétrie non critiques qui n'affectent pas les fonctionnalités de base.

Avertissements relatifs aux migrations

Modèle de journal (dans qchat.log) : « La migration n'a pas eu lieu pour la raison suivante : Annulation de la migration »

Solution : Il s'agit généralement d'un avertissement non critique lié à la migration de configuration qui peut généralement être ignoré.

Authentication failures (Échecs d’authentification)

Modèle de journal (dans chat.log) : erreurs liées à l'authentification dans les opérations du SDK AWS

Solution : exécutez q login pour vous réauthentifier ou vérifier vos informations d'identification AWS

Problèmes de connectivité réseau

Modèle de journal (dans chat.log) : « Expiration de la connexion », « Réseau inaccessible » ou échec des connexions HTTP

Solution : vérifiez les paramètres de votre connexion Internet et de votre pare-feu

Défaillances de fonctionnement du SDK AWS

Modèle de journal (dans chat.log) : échec des opérations Cognito Identity ou erreurs de récupération des informations d'identification

Solution : vérifiez vos informations d'identification AWS et votre connectivité réseau. Peut nécessiter une nouvelle authentification

Obtenir de l'aide pour l'analyse des journaux

Si vous avez besoin d'aide pour analyser les journaux ou résoudre des problèmes :

• Lorsque vous contactez le support, incluez les extraits de journal pertinents (les informations sensibles ayant été supprimées)

• Indiquez le contexte dans lequel le problème se produit et les étapes à suivre pour le reproduire