Accesso e utilizzo dei log di Amazon Q Developer - Amazon Q Developer
Panoramica dell’accesso al logLog dell’estensione IDELog della CLI di Amazon QModelli di log e soluzioni comuniOttenere assistenza con l’analisi dei log

Accesso e utilizzo dei log di Amazon Q Developer

Amazon Q Developer genera log dettagliati in grado di aiutarti a diagnosticare e risolvere i problemi. Questa guida mostra come accedere ai log per diverse interfacce Amazon Q e configurare i livelli di registrazione dei log per ottenere le informazioni necessarie per la risoluzione dei problemi.

Navigazione rapida:

Panoramica dell’accesso al log

Sono disponibili due modalità principali per accedere ai log di Amazon Q Developer, a seconda di come utilizzi il servizio:

  • Estensioni IDE: gli IDE VS Code e JetBrains sono dotati di un pulsante “Mostra log” per accedere ai log specifici di Amazon Q

  • Interfaccia della riga di comando (Amazon Q CLI): i log vengono archiviati localmente in directory temporanee con livelli di dettaglio configurabili

Importante

I file di log possono contenere informazioni sensibili relative alle conversazioni e alle interazioni con Amazon Q, inclusi percorsi di file, frammenti di codice, output di comandi, ID account e nomi di risorse. Presta attenzione quando condividi i file di log con altri.

Log dell’estensione IDE

Accesso ai log tramite l’interfaccia IDE

  1. Apri il pannello di chat di Amazon Q nel tuo IDE (VS Code o JetBrains)

  2. Fai clic sul pulsante Mostra log nell’angolo in alto a destra del pannello della chat

  3. Conferma l’avviso di sensibilità che appare

  4. La posizione del file di log verrà aperta nel file manager del sistema per essere esaminata

Analisi dei log dell’estensione IDE

Quando esamini i log dell’estensione IDE, cerca:

  • Messaggi di errore: le righe contenenti “ERROR” o “FATAL” indicano problemi critici

  • Problemi di autenticazione: cerca gli errori relativi all’autenticazione o alle credenziali

  • Connettività di rete: timeout di connessione o errori relativi alla rete

  • Errori specifici delle funzionalità: problemi relativi ai suggerimenti di codice, alla chat o ad altre funzionalità specifiche

Log della CLI di Amazon Q

La CLI di Amazon Q genera automaticamente dei log completi per tutte le operazioni, indipendentemente dalle impostazioni di dettaglio. I log vengono sempre scritti su file, mentre i flag di dettaglio controllano solo ciò che appare nell’output del terminale.

Posizioni e file dei log della CLI di Amazon Q

I log della CLI di Amazon Q vengono archiviati automaticamente nelle seguenti posizioni:

Sistema operativo Posizione dei log
macOS $TMPDIR/qlog/(in genere /var/folders/.../qlog/)
Linux/WSL $XDG_RUNTIME_DIR/qlog/ o $TMPDIR/qlog/ o /tmp/qlog/
Windows %TEMP%\qlog\

La CLI di Amazon Q crea automaticamente più file di log specializzati:

chat.log - I principali log wrapper della CLI di Amazon Q, tra cui:

  • Operazioni di avvio e inizializzazione della CLI di Amazon Q

  • Chiamate SDK AWS (Cognito Identity, flussi di autenticazione)

  • Operazioni di rete (connessioni HTTP/TLS, gestione dei certificati)

  • Operazioni di sistema a basso livello (telemetria, connessioni socket)

  • Risoluzione degli endpoint dei servizi AWS e pool di connessioni

  • Informazioni di debugging dettagliate per i componenti dell’infrastruttura

qchat.log - Log specifici delle applicazioni di chat, tra cui:

  • Errori delle applicazioni di chat e problemi di elaborazione dello stato

  • Errori di connessione e gestione del server Model Context Protocol (MCP)

  • Problemi relativi alla migrazione a livello di applicazione

  • Interruzioni delle interazioni con gli utenti ed errori di elaborazione della chat

  • Errori della logica dell’applicazione di livello superiore

mcp.log - Log del server Model Context Protocol (compilati quando si utilizzano dei server MCP)
translate.log - Log di traduzione dal linguaggio naturale alla shell (compilati quando si utilizza la funzionalità di traduzione)

Principali differenze tra file di log

Differenze di ambito e dettaglio:

  • chat.log: registrazione di log completa a livello di sistema che copre l’intera infrastruttura della CLI di Q

  • qchat.log: registrazione di log mirata a livello di applicazione specifica per la funzionalità di chat

Differenze di focalizzazione dei contenuti:

  • chat.log: componenti interni di AWS SDK, protocolli di rete, flussi di autenticazione, operazioni di sistema

  • qchat.log: logica della chat, ciclo di vita del server MCP, problemi relativi all’esperienza utente, errori delle applicazioni

Nota

I file di log vengono archiviati solo sul computer locale e non vengono inviati ad AWS. Tutti i file di log vengono creati automaticamente quando si utilizza per la prima volta la CLI, anche senza flag dettagliati.

Flusso di lavoro di risoluzione dei problemi della CLI di Amazon Q

Segui questo approccio per raccogliere informazioni sulla diagnostica dai log.

  1. Identifica la directory di log del tuo sistema:

    Su Linux/WSL:

    echo $XDG_RUNTIME_DIR/qlog/

    Su macOS:

    echo $TMPDIR/qlog/

    In Windows:

    echo %TEMP%\qlog\

  2. Esegui il comando della CLI di Amazon Q con il massimo dettaglio per visualizzare l’output dettagliato nel tuo terminale:

    q -vvv chat

  3. Riproduci il problema che stai riscontrando

  4. Esci dalla CLI di Amazon Q ed esamina i file di log pertinenti. Per la maggior parte dei problemi, controlla entrambi i file di log principali:

    Su macOS o Linux:

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

    Alternativa su macOS:

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

    In Windows:

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

  5. Per il monitoraggio dei log in tempo reale durante la risoluzione dei problemi, usa:

    Monitora tutti i file di log contemporaneamente:

    tail -f $XDG_RUNTIME_DIR/qlog/*.log

    Monitora file specifici:

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

Analisi dei log della CLI di Amazon Q

I log della CLI di Amazon Q utilizzano livelli di registrazione di log standard per classificare le informazioni in base all’importanza:

ERRORE

Problemi critici che impediscono il normale funzionamento: inizia da qui per la risoluzione dei problemi

WARN

Potenziali problemi che non impediscono la funzionalità ma che devono essere segnalati

INFO

Messaggi operativi generali sull’attività dell’applicazione

DEBUG

Informazioni tecniche dettagliate utili per un’indagine più approfondita

Quando esamini i log della CLI di Amazon Q, concentrati su queste aree chiave nei diversi file di log:

Analisi qchat.log - Problemi a livello di applicazione, tra cui:

  • ERROR chat_cli::cli::chat - Errori di elaborazione della chat e gestione dello stato

  • ERROR chat_cli::cli::agent - Problemi relativi alla migrazione e agli agenti

  • ERROR chat_cli::telemetry - Convalida della telemetria ed errori di trasmissione

Analisi chat.log - Dettagli operativi di runtime, tra cui:

  • DEBUG q_cli::cli - Esecuzione e inizializzazione di dei comandi della CLI di Amazon Q

  • DEBUG aws_sdk_* - Operazioni e chiamate di servizio AWS SDK

  • DEBUG rustls::* - Avvio della connessione TLS/SSL e gestione dei certificati

  • DEBUG hyper_* - Gestione delle connessioni HTTP e operazioni di rete

  • ERROR fig_telemetry - Problemi di telemetria del sistema e di connessione del socket

Suggerimenti generali per l’analisi:

  • Timestamp - Correla le voci di log con il momento in cui si sono verificati i problemi

  • Schemi di errore - Cerca gli errori ripetuti o gli errori in cascata

  • Request ID - Monitora chiamate API specifiche e i relativi risultati

  • Stati di connessione - Monitora la connettività di rete e lo stato di autenticazione

Suggerimento

Utilizza strumenti come grep, awk o editor di testo con funzionalità di ricerca, per filtrare i log in base a messaggi o schemi di errore specifici. Ad esempio: grep -i error $XDG_RUNTIME_DIR/qlog/*.log

Modelli di log e soluzioni comuni

Ecco alcuni problemi comuni che potresti riscontrare nei log e le relative soluzioni tipiche:

Errori di connessione con il server MCP

Schema di log (in qchat.log): “Background listening thread for client [server-name]: RecvError(Closed)” oppure “All senders dropped for transport layer”

Soluzione: i processi del server MCP hanno smesso di funzionare. Questo è in genere un comportamento previsto quando si esce dalla CLI di Amazon Q o quando i server si spengono normalmente.

Interruzioni dell’elaborazione della chat

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

Soluzione: questo errore si verifica quando le operazioni di chat vengono annullate dall’utente (ad esempio, Ctrl+C) ed è un comportamento previsto.

Errori di convalida della telemetria

Schema di registro (in qchat.log): “Failed to send cw telemetry event err=ValidationError [ValidationException]: Improperly formed request”

Soluzione: in genere si tratta di problemi non critici di trasmissione telemetrica che non influiscono sulle funzionalità di base.

Avvertenze sulla migrazione

Schema di log (in qchat.log): “Migration did not happen for the following reason: Aborting migration”

Soluzione: si tratta di un avviso non critico relativo alla migrazione della configurazione e in genere può essere ignorato.

Authentication failures (Errori di autenticazione)

Schema di log (in chat.log): errori relativi all’autenticazione nelle operazioni dell’SDK AWS

Soluzione: esegui q login per riautenticare o controllare le tue credenziali AWS

Eventi di connettività di rete

Schema di log (in chat.log): “Connection timeout”, “Network unreachable"” o connessioni HTTP non riuscite

Soluzione: controlla la connessione di rete e le impostazioni firewall

Guasti operativi dell’SDK AWS

Schema di log (in chat.log): operazioni di Cognito Identity non riuscite o errori di recupero delle credenziali

Soluzione: verifica le credenziali AWS e la connettività di rete. Potrebbe richiedere una nuova autenticazione

Ottenere assistenza con l’analisi dei log

Se hai bisogno di assistenza per l’analisi dei log o la risoluzione di problemi:

  • Quando contatti l’assistenza, includi gli estratti dei log pertinenti (con le informazioni sensibili rimosse)

  • Fornisci un contesto su quando si verifica il problema e sulle fasi per riprodurlo