Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # 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](#log-access-overview) + [Protokolle der IDE-Erweiterungen](#ide-logs) + [Protokolle der Amazon Q CLI](#cli-logs) + [Allgemeine Protokollmuster und Lösungen](#common-log-patterns) + [Hilfe bei der Protokollanalyse](#getting-help-with-logs) ## Ü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 Amazon Q-spezifische 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, Codefragmente, Befehlsausgaben IDs, Konto- 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 Amazon Q-Chat-Panel in Ihrer IDE (VS Code oder JetBrains) 1. Klicken Sie in der oberen rechten Ecke des Chat-Panels auf die Schaltfläche **Protokolle anzeigen**. 1. Bestätigen Sie die angezeigte Warnung im Hinblick auf sensible Daten. 1. 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 | \$1TMPDIR/qlog/ (in der Regel /var/folders/.../qlog/) | | Linux/WSL | \$1XDG\$1RUNTIME\$1DIR/qlog/, \$1TMPDIR/qlog/ oder /tmp/qlog/ | | Windows | %TEMP%\$1qlog\$1 | 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 diese gesendet AWS. 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\ ``` 1. 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 ``` 1. Reproduzieren Sie das Problem, das bei Ihnen auftritt. 1. 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 ``` 1. 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\$1cli::cli::chat** – Fehler bei der Chat-Verarbeitung und Statusverwaltung + **ERROR chat\$1cli::cli::agent** – Probleme mit der Migration und mit Agenten + **ERROR chat\$1cli::telemetry** – Telemetrievalidierungs- und Übertragungsfehler `chat.log`-Analyse – Betriebsdetails zur Laufzeit, einschließlich: + **DEBUG q\$1cli::cli** – Ausführung und Initialisierung von Befehlen der Amazon Q CLI + **DEBUG aws\$1sdk\$1\$1** – AWS-SDK-Operationen und Serviceaufrufe + **DEBUG rustls: :\$1** - TLS/SSL Verbindungsaufbau und Umgang mit Zertifikaten + **DEBUG hyper\$1\$1** – Verwaltung von HTTP-Verbindungen und Netzwerkoperationen + **ERROR fig\$1telemetry** – 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. + **Anfrage IDs** — Verfolge spezifische 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 \$1XDG\$1RUNTIME\$1DIR/qlog/\$1.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):** „Hintergrund-Listening-Thread für Client [Servername]: RecvError (Geschlossen)“ oder „Alle Absender wurden für die Transportschicht gelöscht“ **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 \$1 tool\$1uses: None \$1“ **Lösung:** Dieser Fehler tritt auf, wenn Chat-Operationen vom Benutzer abgebrochen werden (z. B. Strg\$1C) und entspricht dem erwarteten Verhalten. Telemetrievalidierungsfehler **Protokollmuster (in qchat.log):** „Fehler beim Senden des CW-Telemetrie-Ereignisses err= ValidationError [ValidationException]: Falsch formatierte Anfrage“ **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.