Zugreifen auf und Verwenden der Protokolle von Amazon Q Developer - Amazon Q Developer
Überblick über den ProtokollzugriffProtokolle der IDE-ErweiterungenProtokolle der Amazon Q CLIAllgemeine Protokollmuster und LösungenHilfe bei der Protokollanalyse

Zugreifen auf und Verwenden der Protokolle von Amazon Q Developer

Amazon Q Developer generiert detaillierte Protokolle, die Ihnen bei der Diagnose und Lösung von Problemen helfen können. In diesem Handbuch erfahren Sie, wie Sie auf Protokolle für verschiedene Amazon-Q-Schnittstellen zugreifen und Protokollierungsebenen konfigurieren, um die Informationen zu erhalten, die Sie für die Fehlerbehebung benötigen.

Schnelle Navigation:

Überblick über den Protokollzugriff

Je nachdem, wie Sie den Service nutzen, gibt es zwei Möglichkeiten, auf Protokolle von Amazon Q Developer zuzugreifen:

  • IDE-Erweiterungen – VS-Code- und JetBrains-IDEs verfügen über eine Schaltfläche „Protokolle anzeigen“ für den Zugriff auf spezifische Amazon-Q-Protokolle.

  • Befehlszeilenschnittstelle (Amazon Q CLI) – Protokolle werden lokal in temporären Verzeichnissen mit konfigurierbaren Detailebenen gespeichert.

Wichtig

Protokolldateien können vertrauliche Informationen aus Ihren Konversationen und Interaktionen mit Amazon Q enthalten, darunter Dateipfade, Codeausschnitte, Befehlsausgaben, Konto-IDs und Ressourcennamen. Seien Sie vorsichtig, wenn Sie Protokolldateien mit anderen teilen.

Protokolle der IDE-Erweiterungen

Zugreifen auf Protokolle über die IDE-Schnittstelle

  1. Öffnen Sie das Chat-Panel von Amazon Q in Ihrer IDE (VS Code oder JetBrains).

  2. Klicken Sie in der oberen rechten Ecke des Chat-Panels auf die Schaltfläche Protokolle anzeigen.

  3. Bestätigen Sie die angezeigte Warnung im Hinblick auf sensible Daten.

  4. Der Speicherort der Protokolldatei wird im Dateimanager Ihres Systems zur Überprüfung geöffnet.

Analysieren von IDE-Erweiterungsprotokollen

Achten Sie bei der Überprüfung der IDE-Erweiterungsprotokolle auf Folgendes:

  • Fehlermeldungen – Zeilen, die „ERROR“ oder „FATAL“ enthalten, weisen auf kritische Probleme hin.

  • Authentifizierungsprobleme – Suchen Sie nach Fehlern im Zusammenhang mit der Authentifizierung oder den Anmeldeinformationen.

  • Netzwerkkonnektivität – Halten Sie Ausschau nach Verbindungstimeouts oder netzwerkbedingte Fehler.

  • Funktionsspezifische Fehler – Achten Sie auf Probleme im Zusammenhang mit Codevorschlägen, Chat oder anderen spezifischen Funktionen.

Protokolle der Amazon Q CLI

Die Amazon Q CLI generiert automatisch umfassende Protokolle für alle Operationen, unabhängig von den Ausführlichkeitseinstellungen. Protokolle werden immer in Dateien geschrieben, wobei Ausführlichkeits-Flags nur steuern, was in der Terminalausgabe angezeigt wird.

Protokollspeicherorte und Dateien der Amazon Q CLI

Protokolle der Amazon Q CLI werden automatisch an den folgenden Speicherorten abgelegt:

Betriebssystem Protokollspeicherort
macOS $TMPDIR/qlog/ (in der Regel /var/folders/.../qlog/)
Linux/WSL $XDG_RUNTIME_DIR/qlog/, $TMPDIR/qlog/ oder /tmp/qlog/
Windows %TEMP%\qlog\

Die Amazon Q CLI erstellt automatisch mehrere spezialisierte Protokolldateien:

chat.log – Die wichtigsten Wrapper-Protokolle der Amazon Q CLI, darunter:

  • Initialisierungs- und Startup-Vorgänge der Amazon Q CLI

  • AWS-SDK-Aufrufe (Cognito Identity, Authentifizierungsabläufe)

  • Netzwerkoperationen (HTTP/TLS-Verbindungen, Umgang mit Zertifikaten)

  • Systemoperationen auf niedriger Ebene (Telemetrie, Socket-Verbindungen)

  • AWS-Serviceendpunktauflösung und Verbindungspooling

  • Detaillierte Debugging-Informationen für Infrastrukturkomponenten

qchat.log – Anwendungsspezifische Chat-Protokolle, einschließlich:

  • Fehler bei der Chat-Anwendung und Probleme bei der Statusverarbeitung

  • MCP (Model Context Protocol)-Servermanagement und Verbindungsfehler

  • Probleme bei der Migration auf Anwendungsebene

  • Unterbrechungen der Benutzerinteraktion und Fehler bei der Chatverarbeitung

  • Fehler in der Anwendungslogik auf höherer Ebene

mcp.log – Serverprotokolle von Model Context Protocol (werden bei Verwendung von MCP-Servern aufgefüllt)
translate.log – Protokolle der Übersetzungen von natürlicher Sprache in die Shell (werden bei Verwendung der Übersetzungsfunktion aufgefüllt)

Hauptunterschiede zwischen Protokolldateien

Unterschiede im Hinblick auf Umfang und Details:

  • chat.log: umfassende Protokollierung auf Systemebene, die die gesamte Q-CLI-Infrastruktur abdeckt

  • qchat.log: spezifische Protokollierung auf Anwendungsebene, die speziell auf die Chat-Funktionalität zugeschnitten ist

Unterschiede bei der inhaltlichen Ausrichtung:

  • chat.log: Interne Funktionen des AWS SDK, Netzwerkprotokolle, Authentifizierungsabläufe, Systemoperationen

  • qchat.log: Chat-Logik, MCP-Serverlebenszyklus, Probleme mit der Benutzererfahrung, Anwendungsfehler

Anmerkung

Protokolldateien werden nur auf Ihrem lokalen Computer gespeichert und nicht an AWS gesendet. Alle Protokolldateien werden automatisch erstellt, wenn Sie die CLI zum ersten Mal verwenden, auch ohne Ausführlichkeits-Flags.

Workflow zur Problembehebung bei der Amazon Q CLI

Gehen Sie wie folgt vor, um Diagnoseinformationen aus den Protokollen zu sammeln.

  1. Identifizieren Sie das Protokollverzeichnis für Ihr System:

    Unter Linux/WSL:

    echo $XDG_RUNTIME_DIR/qlog/

    Unter macOS:

    echo $TMPDIR/qlog/

    Unter Windows:

    echo %TEMP%\qlog\

  2. Führen Sie den Befehl der Amazon Q CLI mit maximaler Ausführlichkeit aus, um eine detaillierte Ausgabe in Ihrem Terminal zu sehen:

    q -vvv chat

  3. Reproduzieren Sie das Problem, das bei Ihnen auftritt.

  4. Beenden Sie die Amazon Q CLI und überprüfen Sie die entsprechenden Protokolldateien. Überprüfen Sie bei den meisten Problemen beide Hauptprotokolldateien:

    Unter macOS/Linux:

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

    Alternativ unter macOS:

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

    Unter Windows:

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

  5. Verwenden Sie für die Protokollüberwachung in Echtzeit während der Fehlerbehebung Folgendes:

    Überwachen Sie alle Protokolldateien gleichzeitig:

    tail -f $XDG_RUNTIME_DIR/qlog/*.log

    Überwachen Sie bestimmte Dateien:

    tail -f $XDG_RUNTIME_DIR/qlog/qchat.log
    tail -f $XDG_RUNTIME_DIR/qlog/chat.log

Analysieren von Protokollen der Amazon Q CLI

Protokolle der Amazon Q CLI verwenden Standardprotokollierungsebenen, um Informationen nach Wichtigkeit zu kategorisieren:

ERROR

Kritische Probleme, die den normalen Betrieb verhindern – beginnen Sie hier mit der Fehlerbehebung.

WARN

Mögliche Probleme, die die Funktionalität nicht beeinträchtigen, aber zur Kenntnis genommen werden sollten

INFO

Allgemeine Betriebsmeldungen darüber, was die Anwendung ausführt

DEBUG

Detaillierte technische Informationen, die für eingehendere Untersuchungen nützlich sind

Konzentrieren Sie sich bei der Untersuchung von Protokollen der Amazon Q CLI auf die folgenden Hauptbereiche in den verschiedenen Protokolldateien:

qchat.log-Analyse – Probleme auf Anwendungsebene, einschließlich:

  • ERROR chat_cli::cli::chat – Fehler bei der Chat-Verarbeitung und Statusverwaltung

  • ERROR chat_cli::cli::agent – Probleme mit der Migration und mit Agenten

  • ERROR chat_cli::telemetry – Telemetrievalidierungs- und Übertragungsfehler

chat.log-Analyse – Betriebsdetails zur Laufzeit, einschließlich:

  • DEBUG q_cli::cli – Ausführung und Initialisierung von Befehlen der Amazon Q CLI

  • DEBUG aws_sdk_* – AWS-SDK-Operationen und Serviceaufrufe

  • DEBUG rustls::* – Aufbau einer TLS/SSL-Verbindung und Umgang mit Zertifikaten

  • DEBUG hyper_* – Verwaltung von HTTP-Verbindungen und Netzwerkoperationen

  • ERROR fig_telemetry – Probleme mit der Systemtelemetrie und der Socket-Verbindung

Allgemeine Analysetipps:

  • Zeitstempel – Korrelieren Sie Protokolleinträge mit dem Zeitpunkt, zu dem Probleme aufgetreten sind.

  • Fehlermuster – Suchen Sie nach wiederholten Fehlern oder Fehlerkaskaden.

  • Anforderungs-IDs – Verfolgen Sie bestimmte API-Aufrufe und deren Ergebnisse.

  • Verbindungsstatus – Überwachen Sie die Netzwerkkonnektivität und den Authentifizierungsstatus.

Tipp

Verwenden Sie Tools wie grep, awk oder Texteditoren mit Suchfunktion, um Protokolle nach bestimmten Fehlermeldungen oder Mustern zu filtern. Beispiel: grep -i error $XDG_RUNTIME_DIR/qlog/*.log

Allgemeine Protokollmuster und Lösungen

Hier sind einige häufig auftretende Probleme, auf die Sie in Protokollen stoßen könnten, und deren typische Lösungen:

MCP-Server-Verbindungsfehler

Protokollmuster (in qchat.log): „Background listening thread for client [server-name]: RecvError(Closed)“ oder „All senders dropped for transport layer“

Lösung: MCP-Serverprozesse laufen nicht mehr. Dieses Verhalten wird normalerweise beim Beenden der Amazon Q CLI oder beim normalen Herunterfahren von Servern erwartet.

Unterbrechungen der Chat-Verarbeitung

Protokollmuster (in qchat.log): „An error occurred processing the current state err=Interrupted { tool_uses: None }“

Lösung: Dieser Fehler tritt auf, wenn Chat-Operationen vom Benutzer abgebrochen werden (z. B. Strg+C) und entspricht dem erwarteten Verhalten.

Telemetrievalidierungsfehler

Protokollmuster (in qchat.log): „Failed to send cw telemetry event err=ValidationError [ValidationException]: Improperly formed request“

Lösung: Dabei handelt es sich in der Regel um unkritische Probleme bei der Telemetrieübertragung, die die Kernfunktionalität nicht beeinträchtigen.

Migrationswarnungen

Protokollmuster (in qchat.log): „Migration did not happen for the following reason: Aborting migration“

Lösung: Dies ist in der Regel eine unkritische Warnung im Zusammenhang mit der Konfigurationsmigration und kann normalerweise ignoriert werden.

Authentication failures (Authentifizierungsfehler)

Protokollmuster (in chat.log): Authentifizierungsbedingte Fehler bei AWS-SDK-Operationen

Lösung: Führen Sie q login aus, um Ihre AWS-Anmeldeinformationen erneut zu authentifizieren oder zu überprüfen.

Probleme mit der Netzwerkkonnektivität

Protokollmuster (in chat.log): „Connection timeout“, „Network unreachable“ oder fehlgeschlagene HTTP-Verbindungen

Lösung: Überprüfen Sie Ihre Netzwerkverbindung und die Firewall-Einstellungen.

AWS-SDK-Betriebsfehler

Protokollmuster (in chat.log): Fehlgeschlagene Cognito-Identity-Operationen oder Fehler beim Abrufen von Anmeldeinformationen

Lösung: Überprüfen Sie Ihre AWS-Anmeldeinformationen und die Netzwerkkonnektivität. Möglicherweise ist eine erneute Authentifizierung erforderlich.

Hilfe bei der Protokollanalyse

Wenn Sie Unterstützung bei der Analyse von Protokollen oder der Lösung von Problemen benötigen:

  • Wenn Sie sich an den Support wenden, fügen Sie relevante Protokollauszüge bei (wobei vertrauliche Informationen entfernt wurden).

  • Erläutern Sie, wann das Problem aufgetreten ist, und geben Sie die Schritte an, mit denen es reproduziert werden kann.