Come faccio ad attivare i log di CloudWatch per la risoluzione dei problemi relativi alla mia REST API di API Gateway o alla mia API WebSocket?

5 minuti di lettura

Devo eseguire il debug degli errori con una REST API o un'API WebSocket del Gateway Amazon API che sto sviluppando. Come posso attivare la registrazione per risolvere i problemi relativi alla mia API?

Breve descrizione

Per risolvere i problemi di una REST API o di un'API WebSocket di API Gateway, attiva la registrazione delle esecuzioni e la registrazione degli accessi utilizzando i File di log Amazon CloudWatch.

**Nota:le **API HTTP attualmente supportano solo la registrazione degli accessi e la configurazione della registrazione è diversa per queste API. Per ulteriori informazioni, consulta Configurazione della registrazione per un'API HTTP.

I log di esecuzione contengono informazioni che è possibile utilizzare per identificare e risolvere la maggior parte degli errori delle API. Ad esempio:

Le richieste ricevute dalla tua API
Le risposte del backend di integrazione dalla tua API
La risposta fornita dai sistemi di autorizzazione AWS Lambda
Il requestId per gli endpoint di integrazione AWS
Informazioni sull'autorizzazione di una chiave API fornita

I log di accesso contengono dettagli su chi ha effettuato l'accesso alla tua API e su come è stato effettuato l'accesso. Puoi anche utilizzare i log per risolvere gli errori delle API. Per ulteriori informazioni su ogni tipo di registrazione, consulta Formati dei log di CloudWatch per API Gateway.

Risoluzione

Crea un ruolo IAM per l'accesso a CloudWatch

1. Nella console AWS Identity and Access Management (IAM), nel riquadro di navigazione, scegli Ruoli.

2. Nel riquadro Ruoli, scegli Crea ruolo.

3. Nella pagina Crea ruolo, procedi come segue:
Per il tipo di Entità affidabile, scegli AWS Service.
Per casi d'uso, scegli API Gateway.
Scegli il pulsante di opzione API Gateway.
Scegli Avanti.

4. In Policy di autorizzazione, tieni presente che la policy gestita da AWS AmazonAPIGatewayPushToCloudWatchLogs è selezionata per impostazione predefinita. La policy dispone di tutte le autorizzazioni richieste.

5. Scegli Avanti.

6. Nella sezione Nomina, rivedi e crea, procedi come segue:
In Nome del ruolo, inserisci un nome per il ruolo.
(Facoltativo) Per la Descrizione del ruolo, modifica la descrizione in base alle tue preferenze.
(Facoltativo) Aggiungi tag.
Scegli Crea ruolo.

7. Nel riquadro Ruoli, nella barra di ricerca, inserisci il nome del ruolo che hai creato. Quindi, scegli il ruolo dai risultati della ricerca.

8. Nel riquadro Riepilogo, copia l'ARN del ruolo. Questo nome della risorsa Amazon (ARN) ti servirà nella prossima sezione.

Per ulteriori informazioni, consulta Autorizzazioni per la registrazione di CloudWatch.

Aggiungi il ruolo IAM nella console API Gateway

Nota: se stai sviluppando più API in diverse regioni AWS, completa questi passaggi in ciascuna regione.

1. Nella Console API Gateway, nel riquadro API, scegli il nome di un'API che hai creato. Dev’essere una REST API o un'API WebSocket (non un'API HTTP).

2. Nel riquadro di navigazione a sinistra, in basso, sotto la sezione Certificati client, scegli Impostazioni.

3. In Impostazioni, per il Ruolo del log ARN di CloudWatch, incolla l'ARN del ruolo IAM che hai copiato.

4. Scegli Salva.
Nota: la console non conferma che l'ARN è stato salvato.

Attiva la registrazione per l'API e la fase

1. Nella console API Gateway, nel riquadro API, scegli il nome di un'API che hai creato.

2. Nel riquadro di navigazione a sinistra, scegli Fase. Quindi, seleziona il nome fase desiderato.

3. Scegli la scheda Logs/Tracing.

4. Nella scheda Logs/Tracing, in Impostazioni CloudWatch, procedi come segue per attivare la registrazione delle esecuzioni:
Seleziona la casella di controllo Abilita il file di log di CloudWatch.
Per il livello di log, scegli INFO per generare i log di esecuzione per tutte le richieste. Oppure, scegli ERROR per generare i log di esecuzione solo per le richieste alla tua API che generano un errore.
Per le REST API, seleziona la casella di controllo Registra i dati completi delle richieste/risposte. In alternativa, per le API WebSocket, seleziona la casella di controllo Registra i dati completi dei messaggi.

5. In Registrazione personalizzata degli accessi, procedi come segue per attivare la registrazione degli accessi:
Seleziona la casella di controllo Abilita la registrazione degli accessi.
Per ARN di destinazione del log degli accessi, inserisci l'ARN di un Amazon Kinesis Data Firehose (supportato solo nelle REST API) o di un gruppo di log di CloudWatch.

Inserisci un Formato di log. Come modello, scegli CLF, JSON, XML o CSV per visualizzare un esempio in quel formato.

6. Scegli Salva modifiche.
Nota: la console non conferma che le impostazioni siano state salvate.

Per ulteriori informazioni, consulta Configurazione della registrazione dei log delle API di CloudWatch utilizzando la console API Gateway.

Verifica la tua configurazione di registrazione

1. Invia una nuova richiesta alla tua API utilizzando l'applicazione client o uno strumento come l'app Postman o wscat (per le API WebSocket).

2. Nella console CloudWatch, nel riquadro di navigazione a sinistra, in Log, scegli Gruppi di log.

3. Nell'elenco dei Gruppi di log, scegli il gruppo di log dell'API di cui stai eseguendo il debug.
Per le REST API, il nome del gruppo di log è nel seguente formato: API-Gateway-Execution-Logs_apiId/stageName.
Per le API WebSocket, il nome del gruppo di log è nel seguente formato: /aws/apigateway/apiId/stageName.
Nota: i log di accesso si trovano nel gruppo di log il cui ARN è stato specificato quando è stata attivata la registrazione degli accessi.

4. Nell'elenco di Flussi di log, scegli il flusso di log con l'ultima Ora dell'ultimo evento. Questa selezione ti consentirà di visualizzare i messaggi con i dettagli di esecuzione o di accesso della tua richiesta.

Per ulteriori informazioni, consulta Visualizza gli eventi di registro di API Gateway nella console CloudWatch.