Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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](#log-access-overview)
+ [Log dell’estensione IDE](#ide-logs)
+ [Log della CLI di Amazon Q](#cli-logs)
+ [Modelli di log e soluzioni comuni](#common-log-patterns)
+ [Ottenere assistenza con l’analisi dei log](#getting-help-with-logs)
## 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** - VS Code e JetBrains IDEs dispongono di un pulsante «Show Logs» 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 registro possono contenere informazioni sensibili relative alle tue conversazioni e interazioni con Amazon Q, inclusi percorsi di file, frammenti di codice, output di comandi, nomi di account e IDs 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)
1. Fai clic sul pulsante **Mostra log** nell’angolo in alto a destra del pannello della chat
1. Conferma l’avviso di sensibilità che appare
1. 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 | \$1TMPDIR/qlog/(in genere /var/folders/.../qlog/) |
| Linux/WSL | \$1XDG\$1RUNTIME\$1DIR/qlog/ o \$1TMPDIR/qlog/ o /tmp/qlog/ |
| Windows | %TEMP%\$1qlog\$1 |
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 registro vengono archiviati solo sul computer locale e non vengono inviati a 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\
```
1. Esegui il comando della CLI di Amazon Q con il massimo dettaglio per visualizzare l’output dettagliato nel tuo terminale:
```
q -vvv chat
```
1. Riproduci il problema che stai riscontrando
1. 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
```
1. 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\$1cli::cli::chat** - Errori di elaborazione della chat e gestione dello stato
+ **ERROR chat\$1cli::cli::agent** - Problemi relativi alla migrazione e agli agenti
+ **ERROR chat\$1cli::telemetry** - Convalida della telemetria ed errori di trasmissione
Analisi `chat.log` - Dettagli operativi di runtime, tra cui:
+ **DEBUG q\$1cli::cli** - Esecuzione e inizializzazione di dei comandi della CLI di Amazon Q
+ **DEBUG aws\$1sdk\$1\$1** - Operazioni e chiamate di servizio AWS SDK
+ **DEBUG rustls: :\$1** - creazione della TLS/SSL connessione e gestione dei certificati
+ **DEBUG hyper\$1\$1** - Gestione delle connessioni HTTP e operazioni di rete
+ **ERROR fig\$1telemetry** - 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
+ **Richiesta IDs**: 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 \$1XDG\$1RUNTIME\$1DIR/qlog/\$1.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 registro (in qchat.log):** «Thread di ascolto in background per il client [nome-server]: RecvError (Chiuso)» o «Tutti i mittenti sono stati eliminati dal livello di trasporto»
**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 \$1 tool\$1uses: None \$1”
**Soluzione:** questo errore si verifica quando le operazioni di chat vengono annullate dall’utente (ad esempio, Ctrl\$1C) ed è un comportamento previsto.
Errori di convalida della telemetria
**Schema di registro (in qchat.log):** «Impossibile inviare l'evento di telemetria cw err= []: richiesta formata in modo ValidationError errato» ValidationException
**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.
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