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à. # Monitoraggio delle REST API in Gateway API In questa sezione verrà illustrato come monitorare le API utilizzando le metriche CloudWatch, CloudWatch Logs, Firehose e AWS X-Ray. Combinando i log di esecuzione i parametri di CloudWatch, è possibile registrare errori e tracciamenti di esecuzione, nonché monitorare le prestazioni dell'API. È possibile anche registrare i log delle chiamate API in Firehose. Inoltre, puoi utilizzare AWS X-Ray per tracciare le chiamate tramite i servizi di downstream che compongono l'API. **Nota** L'API Gateway potrebbe non generare log e parametri nei seguenti casi: Errori 413 per richiesta troppo grande Errori 431 Campi intestazione richiesta troppo grandi Errori 429 per troppe richieste Errori serie 400 per richieste inviate a un dominio personalizzato che non dispone del mapping API Errori serie 500 per malfunzionamenti interni API Gateway non genererà log e parametri durante il test di un metodo REST API. Le voci CloudWatch sono simulate. Per ulteriori informazioni, consulta [Utilizzo della console API Gateway per il test di un metodo API REST](how-to-test-method.md). **Topics** + [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md) + [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md) + [Registrazione dei log delle chiamate REST API su Amazon Data Firehose in Gateway API](apigateway-logging-to-kinesis.md) + [Variabili per la registrazione dei log degli accessi per Gateway API](api-gateway-variables-for-access-logging.md) + [Traccia delle richieste degli utenti alle REST API utilizzando X-Ray in Gateway API](apigateway-xray.md) # Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon Puoi monitorare l'esecuzione delle API utilizzando CloudWatch, che raccoglie ed elabora i dati grezzi da API Gateway in metriche leggibili. near-real-time Queste statistiche vengono registrate per un periodo di 15 mesi, per permettere l'accesso alle informazioni storiche e offrire una prospettiva migliore sulle prestazioni del servizio o dell'applicazione Web. Per impostazione predefinita, i dati metrici di API Gateway vengono inviati automaticamente CloudWatch in periodi di un minuto. Per ulteriori informazioni, consulta [What Is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) nella *Amazon CloudWatch User Guide*. I parametri forniti dall'API Gateway offrono informazioni che possono essere analizzate in diversi modi. L'elenco seguente mostra alcuni usi comuni dei parametri che sono suggerimenti per iniziare: + Monitora le **IntegrationLatency**metriche per misurare la reattività del backend. + Monitora i parametri **Latency** per misurare la velocità di risposta complessiva delle chiamate API. + Monitora le metriche **CacheHitCount**e le **CacheMissCount**metriche per ottimizzare le capacità della cache e ottenere le prestazioni desiderate. **Topics** + [Dimensioni e parametri di Amazon API Gateway](api-gateway-metrics-and-dimensions.md) + [Visualizzazione dei parametri di CloudWatch con il pannello di controllo delle API in API Gateway](how-to-api-dashboard.md) + [Visualizza le metriche dell'API Gateway nella console CloudWatch](metrics_dimensions_view_in_cloud_watch.md) + [Visualizza gli eventi di registro dell'API Gateway nella CloudWatch console](view-cloudwatch-log-events-in-cloudwatch-console.md) + [Strumenti di monitoraggio in AWS API Gateway](monitoring_automated_manual.md) # Dimensioni e parametri di Amazon API Gateway Le metriche e le dimensioni che API Gateway invia ad Amazon CloudWatch sono elencate di seguito. Per ulteriori informazioni, consulta [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md). ## Parametri di API Gateway Amazon API Gateway invia dati metrici CloudWatch ogni minuto. Lo spazio dei nomi `AWS/ApiGateway` include le metriche descritte di seguito. | Metrica | Descrizione | | --- | --- | | 4XXError | Il numero di errori lato client catturati in un dato periodo. API Gateway conta i codici di stato di risposta del gateway modificati come 4 XXError errori. La statistica `Sum` rappresenta questo parametro, ovvero il numero totale di errori 4XXError nel dato periodo. La statistica `Average` rappresenta la percentuale di errori 4XXError nel dato periodo, ovvero il numero totale di errori 4XXError diviso per il numero totale di richieste durante il periodo. Il denominatore corrisponde al parametro Count (di seguito). Unit: Count | | 5XXError | Il numero di errori lato server catturati in un dato periodo. La statistica `Sum` rappresenta questo parametro, ovvero il numero totale di errori 5XXError nel dato periodo. La statistica `Average` rappresenta la percentuale di errori 5XXError nel dato periodo, ovvero il numero totale di errori 5XXError diviso per il numero totale di richieste durante il periodo. Il denominatore corrisponde al parametro Count (di seguito). Unit: Count | | CacheHitCount | Il numero di richieste servite dalla cache API in un dato periodo. La statistica `Sum` rappresenta questo parametro, ovvero il numero totale di riscontri nella cache nel dato periodo. La statistica `Average` rappresenta la percentuale di riscontri nella cache, ovvero il numero totale di riscontri nella cache diviso per il numero totale di richieste durante il periodo. Il denominatore corrisponde al parametro Count (di seguito). Unit: Count | | CacheMissCount | Il numero di richieste servite dal back-end in un dato periodo, quando la memorizzazione nella cache delle API è abilitata. La statistica `Sum` rappresenta questo parametro, ovvero il numero totale di mancati riscontri nella cache nel dato periodo. La statistica `Average` rappresenta la percentuale di mancati riscontri nella cache, ovvero il numero totale di mancati riscontri nella cache diviso per il numero totale di richieste durante il periodo. Il denominatore corrisponde al parametro Count (di seguito). Unit: Count | | Count | Il numero totale di richieste API in un dato periodo. La statistica `SampleCount` rappresenta questo parametro. Unit: Count | | IntegrationLatency | Il tempo che intercorre tra il momento in cui API Gateway ritrasmette una richiesta al back-end e quando riceve da questo una risposta. Unit: Millisecond | | Latency | Il tempo che intercorre tra il momento in cui API Gateway riceve una richiesta dal client e quando restituisce ad esso una risposta. La latenza include la latenza di integrazione e altri sovraccarichi dell'API Gateway. Unit: Millisecond | ## Dimensioni per i parametri Per filtrare i parametri di API Gateway, puoi utilizzare le dimensioni nella seguente tabella. **Nota** API Gateway rimuove i caratteri non ASCII dalla ApiName dimensione prima di inviare le metriche a. CloudWatch Se APIName non contiene caratteri ASCII, API ID viene utilizzato come ApiName. | Dimensione | Descrizione | | --- | --- | | ApiName | Filtra i parametri dell'API Gateway per l’API REST con il nome API specificato. | | ApiName, Method, Resource, Stage | Filtra i parametri dell'API Gateway per il metodo API con nome API, fase, risorsa e metodo specificati. API Gateway non invierà queste metriche a meno che tu non abbia abilitato esplicitamente le metriche dettagliate CloudWatch . Nella console, scegli una fase, quindi seleziona **Modifica** per **Log e tracciamento**. Seleziona **Parametri dettagliati**, quindi scegli **Salva modifiche**. In alternativa, puoi chiamare il AWS CLI comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) per aggiornare la proprietà a. `metricsEnabled` `true` L'abilitazione di questi parametri comporta addebiti aggiuntivi sul tuo account. Per informazioni sui prezzi, consulta la pagina [ CloudWatchdei prezzi di Amazon](https://aws.amazon.com/cloudwatch/pricing/). | | ApiName, Stage | Filtra i parametri di API Gateway per la risorsa della fase API con il nome e la fase specificati per l'API. | # Visualizzazione dei parametri di CloudWatch con il pannello di controllo delle API in API Gateway È possibile utilizzare il pannello di controllo delle API nella console API Gateway per visualizzare i parametri di CloudWatch dell'API distribuita in API Gateway. Tali parametri sono visualizzati come un riepilogo delle attività delle API nel corso del tempo. **Topics** + [Prerequisiti](#how-to-api-dashboard-prerequisites) + [Esame delle attività nel pannello di controllo delle API](#how-to-api-dashboard-console) ## Prerequisiti 1. Devi aver creato un'API in API Gateway. Segui le istruzioni in [Sviluppa REST APIs in API Gateway](rest-api-develop.md). 1. Devi avere distribuito l'API almeno una volta. Segui le istruzioni in [Implementazione di REST API in Gateway API](how-to-deploy-api.md). ## Esame delle attività nel pannello di controllo delle API 1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Scegliere un'API. 1. Nel pannello di navigazione principale, seleziona **Pannello di controllo**. 1. In **Fase**, scegli la fase desiderata. 1. Scegli **Intervallo di date** per specificare un intervallo di date. 1. Aggiorna, se necessario, e visualizza le singole metriche presenti nei grafici intitolati **Chiamate API**, **Latenza**, **Latenza di integrazione**, **Latenza**, **Errore 4xx** ed **Errore 5xx**. **Suggerimento** Per esaminare i parametri di CloudWatch a livello di metodo, assicurarsi di aver attivato CloudWatch Logs a livello di metodo. Per ulteriori informazioni su come configurare la registrazione dei log a livello di metodo, consultare [Sostituzione delle impostazioni a livello di fase](set-up-stages.md#how-to-method-override). # Visualizza le metriche dell'API Gateway nella console CloudWatch I parametri vengono raggruppati prima in base allo spazio dei nomi del servizio e successivamente in base alle diverse combinazioni di dimensioni all'interno di ogni spazio dei nomi. Per visualizzare le metriche a livello di metodo per l'API, attiva le metriche dettagliate. Per ulteriori informazioni, consulta [Modifica delle impostazioni di fase](set-up-stages.md#how-to-stage-settings). **Per visualizzare le metriche dell'API Gateway utilizzando la console CloudWatch** 1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Se necessario, modifica Regione AWS. Dalla barra di navigazione, seleziona la regione in cui risiedono AWS le tue risorse. 1. Nel riquadro di navigazione, seleziona **Parametri**. 1. Nella scheda **All metrics (Tutti i parametri)**, scegliere **API Gateway (Gateway API)**. 1. Per visualizzare i parametri in base alla fase, selezionare il pannello **By Stage (Per fase)**. Quindi, seleziona il tuo nome APIs e quello delle metriche. 1. Per visualizzare i parametri in base a un'API specifica, selezionare il pannello **API Name (Nome API)**. Quindi, seleziona il tuo nome APIs e quello delle metriche. **Per visualizzare le metriche utilizzando la CLI AWS** 1. Utilizza il seguente comando [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) per elencare le metriche: ``` aws cloudwatch list-metrics --namespace "AWS/ApiGateway" ``` Dopo aver creato una metrica, occorrono fino a 15 minuti perché venga visualizzata. Per visualizzare più rapidamente le statistiche delle metriche, usa o. [get-metric-data[get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html)](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html) 1. Utilizzate il seguente [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html)comando per visualizzare la media su un periodo di tempo utilizzando intervalli di 5 minuti: ``` aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average ``` # Visualizza gli eventi di registro dell'API Gateway nella CloudWatch console La sezione seguente spiega i prerequisiti necessari e come visualizzare gli eventi di registro di API Gateway nella CloudWatch console. ## Prerequisiti 1. Devi aver creato un'API in API Gateway. Segui le istruzioni in [Sviluppa REST APIs in API Gateway](rest-api-develop.md). 1. È necessario avere implementato e richiamato l'API almeno una volta. A tale scopo, segui le istruzioni riportate in [Implementazione di REST API in Gateway API](how-to-deploy-api.md) e [Invocazione di REST API in Gateway API](how-to-call-api.md). 1. È necessario che CloudWatch i log siano abilitati per una fase. Segui le istruzioni in [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md). ## Per visualizzare le richieste e le risposte API registrate utilizzando la console CloudWatch 1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Se necessario, modifica Regione AWS. Dalla barra di navigazione, seleziona la regione in cui risiedono AWS le tue risorse. Per ulteriori informazioni, consulta [Regioni ed endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html). 1. Nel pannello di navigazione a sinistra, scegli **Log**, **Gruppi di log**. 1. Nella tabella **Log Groups**, scegliete un gruppo di log del nome **API-Gateway-Execution-Logs\$1** \$1\$1/\$1stage-name\$1. rest-api-id 1. Nella tabella **Log Streams (Flussi di log)**, scegliere un flusso di log. Puoi utilizzare il timestamp per individuare il flusso di log che ti interessa. 1. Selezionare **Text (Testo)** per vedere il testo non elaborato o scegliere **Row (Riga)** per visualizzare l'evento riga dopo riga. **Importante** CloudWatch consente di eliminare gruppi o stream di log. Non eliminare manualmente i gruppi o i flussi di log delle API di API Gateway, lasciare che sia API Gateway a gestire queste risorse. L'eliminazione manuale dei flussi e dei gruppi di log potrebbe causare la mancata registrazione delle richieste e delle risposte dell'API. In tal caso puoi eliminare l'intero gruppo di log dell'API e ridistribuire l'API. Ciò accade perché il Gateway API crea flussi o gruppi di log per una fase API nel momento in cui viene distribuita. # Strumenti di monitoraggio in AWS API Gateway AWS fornisce vari strumenti che è possibile utilizzare per monitorare API Gateway. Alcuni di questi strumenti possono essere configurati in modo che eseguano automaticamente il monitoraggio, mentre altri richiedono l'intervento manuale. Si consiglia di automatizzare il più possibile i processi di monitoraggio. ## Strumenti di monitoraggio automatizzati in AWS Per controllare l'API Gateway e segnalare l'eventuale presenza di problemi è possibile usare i seguenti strumenti di monitoraggio automatici: + **Amazon CloudWatch Alarms**: monitora una singola metrica in un periodo di tempo specificato ed esegui una o più azioni in base al valore della metrica rispetto a una determinata soglia in diversi periodi di tempo. L'azione è una notifica inviata a un argomento di Amazon Simple Notification Service (Amazon SNS) o a una policy di Amazon EC2 Auto Scaling. CloudWatch gli allarmi non richiamano azioni semplicemente perché si trovano in uno stato particolare; lo stato deve essere cambiato e mantenuto per un determinato numero di periodi. Per ulteriori informazioni, consulta [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md). + **Amazon CloudWatch Logs**: monitora, archivia e accedi ai tuoi file di registro da AWS CloudTrail o altre fonti. Per ulteriori informazioni, consulta [What is CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) nella *Amazon CloudWatch User Guide*. + **Amazon EventBridge (precedentemente chiamato CloudWatch Events)**: abbina gli eventi e li indirizza a una o più funzioni o flussi di destinazione per apportare modifiche, acquisire informazioni sullo stato e intraprendere azioni correttive. Per ulteriori informazioni, consulta [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) nella *Guida EventBridge per l'utente*. + **AWS CloudTrail Monitoraggio dei** registri: condividi i file di CloudTrail registro tra account, monitora i file di registro in tempo reale inviandoli a CloudWatch Logs, scrivi applicazioni di elaborazione dei log in Java e verifica che i file di registro non siano stati modificati dopo la consegna da parte di. CloudTrail Per ulteriori informazioni, consulta [Lavorare con i file di CloudTrail registro nella Guida](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) per l'*AWS CloudTrail utente*. ## Strumenti di monitoraggio manuali Un'altra parte importante del monitoraggio di API Gateway riguarda il monitoraggio manuale degli elementi che gli CloudWatch allarmi non coprono. L'API Gateway e altre dashboard della AWS console forniscono una at-a-glance panoramica dello stato dell' AWS ambiente. CloudWatch Consigliamo anche di controllare i file di log nell'esecuzione dell'API. + Il pannello di controllo di API Gateway mostra le seguenti statistiche per una determinata fase API nel corso di un determinato periodo di tempo: + **API Calls (Chiamate API)** + **Cache HIt (Riscontri nella cache)** solo quando è abilitato il caching dell'API. + **Cache Miss (Mancato riscontro nella cache)** solo quando è abilitato il caching dell'API. + **Latenza** + **Integration Latency (Latenza di integrazione)** + **4XX Error (Errore 4XX)** + **5XX Error (Errore 5XX)** + La CloudWatch home page mostra: + Stato e allarmi attuali + Grafici degli allarmi e delle risorse + Stato di integrità dei servizi Inoltre, è possibile utilizzare CloudWatch per effettuare le seguenti operazioni: + Crea [pannelli di controllo personalizzati](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) per monitorare i servizi di interesse. + Crea grafici dei dati dei parametri per la risoluzione di problemi e il rilevamento di tendenze. + Cerca e sfoglia tutte le metriche AWS delle tue risorse + Crea e modifica gli allarmi per ricevere le notifiche dei problemi. ## Creazione di CloudWatch allarmi per monitorare API Gateway Puoi creare un CloudWatch allarme che invia un messaggio Amazon SNS quando l'allarme cambia stato. Un allarme controlla un singolo parametro in un periodo di tempo specificato ed esegue una o più operazioni in base al valore del parametro relativo a una determinata soglia in una serie di periodi di tempo. L'operazione corrisponde all'invio di una notifica a un argomento di Amazon SNS o a una policy di Auto Scaling. Gli allarmi richiamano azioni solo per cambiamenti di stato sostenuti. CloudWatch gli allarmi non richiamano azioni semplicemente perché si trovano in uno stato particolare; lo stato deve essere cambiato e mantenuto per un determinato numero di periodi. # Configurare la CloudWatch registrazione per REST APIs in API Gateway Per risolvere i problemi relativi all'esecuzione della richiesta o all'accesso del client alla tua API, puoi abilitare Amazon CloudWatch Logs per registrare le chiamate API. Per ulteriori informazioni su CloudWatch, consulta. [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md) ## CloudWatch formati di registro per API Gateway Esistono due tipi di accesso tramite API CloudWatch: registrazione dell'esecuzione e registrazione degli accessi. Nella registrazione dell'esecuzione, API Gateway gestisce i CloudWatch log. Il processo include la creazione di gruppi e flussi di log e la segnalazione ai flussi di log delle richieste e delle risposte dell'intermediario. I dati registrati nei log includono errori o tracce di esecuzione (come valori di parametri di richiesta o di risposta oppure payload), dati usati da sistemi di autorizzazione Lambda (noti in precedenza come sistemi di autorizzazione ad hoc), indicazioni sull'eventuale necessità di chiavi API e sull'eventuale abilitazione dei piani di utilizzo e altre informazioni. Gateway API oscura le intestazioni di autorizzazione, i valori delle chiavi API e parametri di richiesta sensibili simili dai dati registrati nei log. Per migliorare il livello di sicurezza, è consigliabile utilizzare la registrazione nei log dell’esecuzione a livello di `ERROR` o `INFO`. Potrebbe essere necessario eseguire questa operazione per rispettare vari framework di conformità. Per ulteriori informazioni, consultare [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) nella *Guida per l’utente di AWS Security Hub *. Quando si distribuisce un'API, API Gateway crea un gruppo di log e i relativi flussi. Al gruppo di log viene assegnato un nome nel formato `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`. All'interno di ciascun gruppo, i log sono suddivisi ulteriormente in flussi, che vengono ordinati in base al valore **Last Event Time** (Ora ultimo evento) quando vengono riportati i dati registrati. Nella registrazione degli accessi, in qualità di sviluppatore dell'API puoi registrare chi ha avuto accesso alla tua API e in che modo l'intermediario ha avuto accesso all'API. Puoi creare un gruppo di log personalizzato o sceglierne uno esistente che potrebbe essere gestito da API Gateway. Per specificare i dettagli di accesso, seleziona le variabili [`$context`](api-gateway-variables-for-access-logging.md), un formato di log e un gruppo di log come destinazione. Il formato del log di accesso deve includere almeno `$context.requestId` o `$context.extendedRequestId`. Come best practice, includere `$context.requestId` e `$context.extendedRequestId` nel formato di log. **`$context.requestId`** In questo modo il valore dell'intestazione `x-amzn-RequestId` viene registrato nel log. I client possono sostituire il valore nell'intestazione `x-amzn-RequestId` con un valore nel formato di un identificatore univoco universale (UUID). API Gateway restituisce questo ID richiesta nell'intestazione della risposta di `x-amzn-RequestId`. API Gateway sostituisce le richieste sovrascritte IDs che non sono in formato UUID nei log di accesso. `UUID_REPLACED_INVALID_REQUEST_ID` **`$context.extendedRequestId`** Il valore di extendedRequestID è un ID univoco generato da Gateway API. API Gateway restituisce questo ID richiesta nell'intestazione della risposta di `x-amz-apigw-id`. Un caller API non può fornire o ignorare questo ID di richiesta. Potrebbe essere necessario fornire questo valore a AWS Support per risolvere i problemi dell'API. Per ulteriori informazioni, consulta [Variabili per la registrazione dei log degli accessi per Gateway API](api-gateway-variables-for-access-logging.md). Seleziona un formato di log adottato anche dal back-end analitico, ad esempio [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF), JSON, XML o CSV. Quindi puoi alimentarlo direttamente con i log di accesso per l'elaborazione e il rendering dei parametri. [Per definire il formato di registro, impostate l'ARN del gruppo di log sulla proprietà [accessLogSettings/destinationARN](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) sullo stage.](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) È possibile ottenere un ARN del gruppo di log nella CloudWatch console. [Per definire il formato del registro degli accessi, impostate un formato scelto nella proprietà [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) sullo stage.](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) Esempi di alcuni formati di log delle operazioni di accesso utilizzati con maggiore frequenza sono mostrati nella console API Gateway ed elencati qui di seguito. + `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)): ``` $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId ``` + `JSON`: ``` { "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" } ``` + `XML`: ``` $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user $context.requestTime $context.httpMethod $context.resourcePath $context.status $context.protocol $context.responseLength ``` + `CSV` (valori separati da virgola): ``` $context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` ## Autorizzazioni per la registrazione CloudWatch Per abilitare CloudWatch i log, devi concedere ad API Gateway l'autorizzazione a leggere e scrivere i log del tuo CloudWatch account. [Amazon APIGateway PushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) dispone di tutte le autorizzazioni necessarie. **Nota** Chiama AWS Security Token Service API Gateway per assumere il ruolo IAM, quindi assicurati che AWS STS sia abilitato per la regione. Per ulteriori informazioni, consulta [Managing AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html). [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) È necessario impostare la proprietà [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) separatamente per ogni AWS regione in cui si desidera abilitare i log. CloudWatch Se ricevi un errore durante l'impostazione dell'ARN del ruolo IAM, controlla le impostazioni AWS Security Token Service dell'account per assicurarti che AWS STS sia abilitato nella regione che stai utilizzando. Per ulteriori informazioni sull'abilitazione AWS STS, consulta [Managing AWS STS in an AWS Region nella](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) *IAM User Guide*. ## Configurare la registrazione delle CloudWatch API utilizzando la console API Gateway Per configurare la registrazione CloudWatch dell'API, è necessario aver distribuito l'API in una fase. È inoltre necessario aver configurato [un ARN del ruolo CloudWatch Logs appropriato](#set-up-access-logging-permissions) per il proprio account. 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Nel pannello di navigazione principale, scegli **Impostazioni**, quindi in **Registrazione** seleziona **Modifica**. 1. Per l'**ARN del ruolo di CloudWatch registro**, inserisci l'ARN di un ruolo IAM con le autorizzazioni appropriate. È necessario eseguire questa operazione una volta per ogni Account AWS creazione creata APIs utilizzando API Gateway. 1. Nel riquadro di navigazione principale, scegli **APIs**, quindi esegui una delle seguenti operazioni: 1. Seleziona un'API esistente e quindi scegli una fase. 1. Crea un'API e implementala in una fase. 1. Nel riquadro di navigazione principale scegli **Fasi**. 1. Nella sezione **Log e tracciamento** scegli **Modifica**. 1. Per abilitare il logging dell'esecuzione: 1. Seleziona un livello di registrazione dal menu a discesa **CloudWatch Registri.** I livelli di registrazione dei log sono: + **Inattivo**: la registrazione dei log non è attivata per questa fase. + **Solo errori**: la registrazione dei log è abilitata solo per gli errori. + **Errori e log informativi**: la registrazione dei log è abilitata per tutti gli eventi. 1. (Facoltativo) Seleziona **Tracciamento dei dati** per attivare la registrazione dei log della traccia dei dati per la fase. Questo può essere utile per la risoluzione dei problemi APIs, ma può comportare la registrazione di dati sensibili. **Nota** Ti consigliamo di non utilizzare il **tracciamento dei dati** per la produzione. APIs 1. (Facoltativo) Seleziona **Metriche dettagliate** per attivare le metriche dettagliate CloudWatch . Per ulteriori informazioni sulle CloudWatch metriche, consulta. [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md) 1. Per abilitare il logging degli accessi: 1. Attiva **Registrazione accesso personalizzato**. 1. Immetti l'ARN di un gruppo di log in **ARN di destinazione del log degli accessi**. Il formato dell'ARN è `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`. 1. In **Formato dei log** immetti un formato di log. Puoi scegliere **CLF**, **JSON**, **XML** o **CSV**. Per ulteriori informazioni sui formati di log di esempio, consulta [CloudWatch formati di registro per API Gateway](#apigateway-cloudwatch-log-formats). 1. Scegli **Save changes** (Salva modifiche). **Nota** Puoi abilitare la registrazione dell'esecuzione e quella degli accessi in modo reciprocamente indipendente. API Gateway ora è pronto a registrare i log delle richieste all'API. Non è necessario ridistribuire l'API quando si aggiornano le impostazioni delle fasi, i log o le variabili delle fasi. ## Configurare la registrazione CloudWatch delle API utilizzando CloudFormation Utilizza il seguente CloudFormation modello di esempio per creare un gruppo di log Amazon CloudWatch Logs e configurare l'esecuzione e la registrazione degli accessi per una fase. Per abilitare CloudWatch i log, devi concedere ad API Gateway l'autorizzazione a leggere e scrivere i log del tuo CloudWatch account. Per ulteriori informazioni, consulta [Associate account with IAM role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples) nella *Guida per l'utente di AWS CloudFormation *. ``` TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment Description: "test stage description" MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO AccessLogSetting: DestinationArn: !GetAtt MyLogGroup.Arn Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId MyLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Join - '-' - - !Ref MyAPI - access-logs ``` # Registrazione dei log delle chiamate REST API su Amazon Data Firehose in Gateway API Per facilitare il debug dei problemi relativi all'accesso dei client all'API, è possibile registrare i log delle chiamate API su Amazon Data Firehose. Per ulteriori informazioni su Firehose, consulta [What Is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) Per la registrazione degli accessi, puoi solo abilitare CloudWatch o FireHose, non puoi abilitare entrambi. Tuttavia, è possibile abilitare CloudWatch la registrazione dell'esecuzione e Firehose la registrazione degli accessi. **Topics** + [Formati di log di Firehose per Gateway API](#apigateway-kinesis-log-formats) + [Autorizzazioni per la registrazione dei log di Firehose](#set-up-kinesis-access-logging-permissions) + [Configurazione della registrazione dei log degli accessi di Firehose tramite la console Gateway API](#set-up-kinesis-access-logging-using-console) ## Formati di log di Firehose per Gateway API [La registrazione Firehose utilizza lo stesso formato della registrazione. CloudWatch ](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html) ## Autorizzazioni per la registrazione dei log di Firehose Quando la registrazione dei log degli accessi di Firehose è abilitata su una fase, Gateway API crea nell'account un ruolo collegato al servizio, se non è già esistente. Il ruolo è denominato `AWSServiceRoleForAPIGateway` ed è collegato alla policy gestita `APIGatewayServiceRolePolicy`. Per ulteriori informazioni sui ruoli collegati ai servizi, consulta [Utilizzo dei ruoli collegati ai servizi](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). **Nota** Il nome del flusso di Firehose deve essere `amazon-apigateway-{your-stream-name}`. ## Configurazione della registrazione dei log degli accessi di Firehose tramite la console Gateway API Per configurare la registrazione API, devi aver distribuito l'API in una fase. È inoltre necessario aver creato un flusso di Firehose. 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Esegui una delle seguenti operazioni: 1. Seleziona un'API esistente e quindi scegli una fase. 1. Crea un'API e distribuiscila in una fase. 1. Nel riquadro di navigazione principale scegli **Fasi**. 1. Nella sezione **Log e tracciamento** scegli **Modifica**. 1. Per abilitare la registrazione dei log degli accessi in un flusso Firehose: 1. Attiva **Registrazione accesso personalizzato**. 1. In **ARN di destinazione del log degli accessi** inserisci l'ARN di un flusso Firehose. Il formato dell'ARN è `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`. **Nota** Il nome del flusso di Firehose deve essere `amazon-apigateway-{your-stream-name}`. 1. In **Formato dei log** immetti un formato di log. Puoi scegliere **CLF**, **JSON**, **XML** o **CSV**. Per ulteriori informazioni sui formati di log di esempio, consulta [CloudWatch formati di registro per API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats). 1. Scegli **Save changes** (Salva modifiche). Gateway API è ora pronto per registrare i log delle richieste all'API su Firehose. Non è necessario ridistribuire l'API quando si aggiornano le impostazioni delle fasi, i log o le variabili delle fasi. # Variabili per la registrazione dei log degli accessi per Gateway API Nella registrazione degli accessi, in qualità di sviluppatore dell'API puoi registrare chi ha avuto accesso alla tua API e in che modo l'intermediario ha avuto accesso all'API. Puoi creare un gruppo di log personalizzato o sceglierne uno esistente che potrebbe essere gestito da API Gateway. Per specificare i dettagli di accesso, è possibile utilizzare le seguenti variabili `$context` con distinzione tra maiuscole e minuscole. Per l’elenco di tutte le variabili di riferimento per le trasformazioni dei dati, consultare [Variabili per le trasformazioni dei dati per Gateway API](api-gateway-mapping-template-reference.md). | Parametro | Description | | --- | --- | | \$1context.accountId | L'ID dell' AWS account del proprietario dell'API. | | \$1context.apiId | Identificatore assegnato da API Gateway all'API. | | \$1context.authorize.error | Il messaggio di errore di autorizzazione. | | \$1context.authorize.latency | La latenza di autorizzazione in ms. | | \$1context.authorize.status | Il codice di stato restituito da un tentativo di autorizzazione. | | \$1context.authorizer.claims.property | Proprietà delle richieste restituite dal pool di utenti di Amazon Cognito dopo che l'intermediario del metodo viene autenticato correttamente. Per ulteriori informazioni, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). La chiamata di `$context.authorizer.claims` restituisce null. | | \$1context.authorizer.error | Il messaggio di errore restituito da un'autorizzazione. | | \$1context.authorizer.integrationLatency | Latenza di integrazione del sistema di autorizzazione in ms. | | \$1context.authorizer.integrationStatus | Il codice di stato restituito da un'autorizzazione Lambda. | | \$1context.authorizer.latency | La latenza di autorizzazione in ms. | | \$1context.authorizer.principalId | Identificazione dell'utente dell'entità principale associata al token inviata dal client e restituita da un'autorizzazione Lambda in API Gateway (precedentemente noto come autorizzazione ad hoc). Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | Valore in formato stringa della coppia chiave/valore specificata della mappa `context` restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa `context` seguente: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
La chiamata di `$context.authorizer.key` restituisce la stringa `"value"`, la chiamata di `$context.authorizer.numKey` restituisce la stringa `"1"` e la chiamata di `$context.authorizer.boolKey` restituisce la stringa `"true"`. Infatti*property*, l'unico carattere speciale supportato è il carattere di sottolineatura`(_)`. Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.requestId | L'ID della richiesta dell' AWS endpoint. | | \$1context.authorizer.status | Il codice di stato restituito da un'autorizzazione. | | \$1context.authenticate.error | Il messaggio di errore restituito da un tentativo di autenticazione. | | \$1context.authenticate.latency | La latenza di autenticazione in ms. | | \$1context.authenticate.status | Il codice di stato restituito da un tentativo di autenticazione. | | \$1context.awsEndpointRequestId | L'ID della richiesta dell' AWS endpoint. | | \$1context.cipherSuite | Il codice, in formato IANA, negoziato durante l'handshake TLS tra il client e API Gateway. | | \$1context.customDomain.basePathMatched | Il percorso per una mappatura API a cui corrisponde una richiesta in ingresso. Applicabile quando un client utilizza un nome di dominio personalizzato per accedere a un'API. Ad esempio, se un client invia una richiesta a `https://api.example.com/v1/orders/1234` e la richiesta corrisponde alla mappatura API con il percorso `v1/orders`, il valore è `v1/orders`. Per ulteriori informazioni, consulta [Usa le mappature delle API per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs](rest-api-mappings.md). | | \$1context.customDomain.routingRuleIdMatched | La regola di routing a cui corrisponde una richiesta in ingresso. Applicabile quando un client utilizza un nome di dominio personalizzato per accedere a un'API. Per ulteriori informazioni, consulta [Regole di routing per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs](rest-api-routing-rules.md). | | \$1context.deploymentId | ID dell'implementazione API. | | \$1context.domainName | Nome di dominio completo usato per richiamare l'API. Deve essere lo stesso dell'intestazione `Host` in ingresso. | | \$1context.domainPrefix | Prima etichetta di `$context.domainName`. | | \$1context.endpointType | Il tipo di endpoint dell'API. | | \$1context.error.message | Stringa contenente un messaggio di errore di API Gateway. Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". | | \$1context.error.responseType | [Un tipo di. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Stringa contenente un messaggio dettagliato di errore di convalida. | | \$1context.extendedRequestId | ID esteso generato da API Gateway e assegnato alla richiesta API. L’ID della richiesta esteso contiene ulteriori informazioni utili per il debug e la risoluzione dei problemi. | | \$1context.httpMethod | Metodo HTTP usato. I valori validi sono: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. | | \$1context.identity.accountId | L'ID dell'account associato alla richiesta. AWS | | \$1context.identity.apiKey | Per i metodi API che richiedono una chiave API, questa variabile è la chiave API associata alla richiesta del metodo. Per i metodi che non richiedono una chiave API, questa variabile è null. Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | ID chiave API associato a una richiesta API che richiede una chiave API. | | \$1context.identity.caller | Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per risorse che utilizzano l'autorizzazione IAM. | | \$1context.identity.cognitoAuthenticationProvider | Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. Ad esempio, per un'identità di un pool di utenti Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono `authenticated` per le identità autenticate e `unauthenticated` per le identità non autenticate. | | \$1context.identity.cognitoIdentityId | ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.principalOrgId | L'[ID organizzazione AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di Gateway API. | | \$1context.identity.clientCert.clientCertPem | Certificato client codificato PEM che il client ha presentato durante l'autenticazione TLS reciproca. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.subjectDN | Nome distinto dell'oggetto del certificato presentato da un client. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.issuerDN | Nome distinto dell'approvatore del certificato presentato da un cliente. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.serialNumber | Il numero di serie del certificato. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.validity.notBefore | La data prima della quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.validity.notAfter | La data dopo la quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.vpcId | L'ID VPC del VPC da cui proviene la richiesta all'endpoint Gateway API. | | \$1context.identity.vpceId | L'ID endpoint VPC dell'endpoint VPC da cui proviene la richiesta all'endpoint Gateway API. Presente solo quando si dispone di un'API privata. | | \$1context.identity.user | Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per risorse che utilizzano l'autorizzazione IAM. | | \$1context.identity.userAgent | Intestazione [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del chiamante API. | | \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. Per ulteriori informazioni, consulta [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.integration.error | Il messaggio di errore restituito da un'integrazione. | | \$1context.integration.integrationStatus | Per l'integrazione del proxy Lambda, il codice di stato restituito dal codice della funzione Lambda di backend AWS Lambda, non dal codice della funzione Lambda. | | \$1context.integration.latency | Latenza di integrazione in ms. Equivalente a \$1context.integrationLatency. | | \$1context.integration.requestId | L'ID della AWS richiesta dell'endpoint. Equivalente a \$1context.awsEndpointRequestId. | | \$1context.integration.responseTransferMode | La modalità di trasferimento delle risposte della tua integrazione. Ciò può essere BUFFERED o STREAMED. | | \$1context.integration.status | Il codice di stato restituito da un'integrazione. Per le integrazioni proxy Lambda, questo è il codice di stato restituito dal codice della funzione Lambda. | | \$1context.integration.timeToAllHeaders | Il tempo che intercorre tra il momento in cui API Gateway stabilisce la connessione di integrazione e il momento in cui riceve tutte le intestazioni di risposta all'integrazione dal client. | | \$1context.integration.timeToFirstContent | Il tempo che intercorre tra il momento in cui API Gateway stabilisce la connessione di integrazione e il momento in cui riceve i primi byte di contenuto. | | \$1context.integrationLatency | Latenza di integrazione in ms. | | \$1context.integrationStatus | Per l'integrazione del proxy Lambda, questo parametro rappresenta il codice di stato restituito dal codice della funzione Lambda di AWS Lambda backend e non dal codice della funzione Lambda. | | \$1context.isCanaryRequest | Restituisce `true` se la richiesta era indirizzata al canary e `false` se la richiesta non era indirizzata al canary. Presente solo quando è abilitato un canary. | | \$1context.path | Percorso della richiesta. Ad esempio, per un URL di richiesta non proxy https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, il valore di \$1context.path è /\$1stage\$1/root/child. | | \$1context.protocol | Protocollo della richiesta, ad esempi, HTTP/1.1. API Gateway APIs può accettare richieste HTTP/2, ma API Gateway invia richieste alle integrazioni di backend utilizzando HTTP/1.1. Di conseguenza, il protocollo di richiesta viene registrato come HTTP/1.1 anche se un client invia una richiesta che utilizza HTTP/2. | | \$1context.requestId | L'ID della richiesta. I client possono sovrascrivere questo ID di richiesta. Utilizza `$context.extendedRequestId` per un ID di richiesta univoco generato da API Gateway. | | \$1context.requestOverride.header.header\$1name | Sovrascrittura intestazione della richiesta. Se definito, questo parametro contiene le intestazioni da utilizzare al posto delle **intestazioni HTTP** che sono definite nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Sovrascrittura percorso della richiesta. Se definito, questo parametro contiene il percorso della richiesta da utilizzare al posto dei **parametri di percorso URL** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Sovrascrittura stringa di query della richiesta. Se definito, questo parametro contiene la stringa di query della richiesta da utilizzare al posto dei **URL Query String Parameters (Parametri stringa di query URL)** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseLatency | Latenza della risposta in ms. | | \$1context.responseLength | Lunghezza del payload della risposta in byte. | | \$1context.responseOverride.header.header\$1name | Sovrascrittura intestazione della risposta. Se definito, questo parametro contiene l'intestazione da restituire al posto della Response header (Intestazione di risposta) che è definita come la Default mapping (mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Sovrascrittura codice di stato della risposta. Se definito, questo parametro contiene il codice di stato da restituire al posto di Method response status (Stato risposta metodo) che è definito come la Default mapping (Mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | L'ora della richiesta in formato [epoca (Unix epoch)](https://en.wikipedia.org/wiki/Unix_time) in millisecondi. | | \$1context.resourceId | Identificatore assegnato da API Gateway alla risorsa. | | \$1context.resourcePath | Percorso della risorsa. Ad esempio, per l'URI della richiesta non proxy di `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, il valore di `$context.resourcePath` è `/root/child`. Per ulteriori informazioni, consulta [Tutorial: creazione di una REST API con un'integrazione non proxy HTTP](api-gateway-create-api-step-by-step.md). | | \$1context.stage | La fase di distribuzione della richiesta API (ad esempio `Beta` o `Prod`). | | \$1context.status | Stato della risposta del metodo. | | \$1context.tlsVersion | La versione TLS negoziata durante l'handshake TLS tra il client e API Gateway. | | \$1context.waf.error | Il messaggio di errore restituito da. AWS WAF | | \$1context.waf.latency | La AWS WAF latenza in ms. | | \$1context.waf.status | Il codice di stato restituito da AWS WAF. | | \$1context.xrayTraceId | L'ID della traccia di X-Ray. Per ulteriori informazioni, consulta [Configurazione AWS X-Ray con API Gateway REST APIs](apigateway-enabling-xray.md). | | \$1context.wafResponseCode | La risposta ricevuta da [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` o `WAF_BLOCK`. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | ARN completo della lista di controllo accessi Web usata per stabilire se consentire o bloccare la richiesta. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | # Traccia delle richieste degli utenti alle REST API utilizzando X-Ray in Gateway API Puoi utilizzare [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) per monitorare e analizzare le richieste degli utenti durante il passaggio attraverso le API REST di Amazon API Gateway verso i servizi sottostanti. API Gateway supporta il monitoraggio attraverso X-Ray per tutti i tipi di endpoint API REST di API Gateway: regionale, ottimizzato per l’edge e privato. Puoi usare X-Ray con Amazon API Gateway in tutte le Regioni AWS in cui X-Ray è disponibile. Poiché X-Ray offre una panoramica completa di un'intera richiesta, puoi analizzare le latenze nelle API e i relativi servizi di back-end. È possibile utilizzare una mappa del servizio di X-Ray per visualizzare la latenza di un'intera richiesta e quella dei servizi downstream integrati con X-Ray. Inoltre, puoi configurare le regole di campionamento per comunicare a X-Ray quali richieste registrare e a quale frequenza in base alle policy specificate. Se chiami un'API di API Gateway da un servizio già tracciato, API Gateway passa subito attraverso il monitoraggio, anche se X-Ray non è abilitato sull'API. È possibile abilitare X-Ray per una fase API utilizzando la console API Gateway o utilizzando l'API o l'interfaccia a riga di comando di API Gateway. **Topics** + [Configurazione AWS X-Ray con API Gateway REST APIs](apigateway-enabling-xray.md) + [Usa le mappe dei AWS X-Ray servizi e traccia le viste con API Gateway](apigateway-using-xray-maps.md) + [Configurazione delle regole AWS X-Ray di campionamento per API Gateway APIs](apigateway-configuring-xray-sampling-rules.md) + [AWS X-Ray tracce per Amazon API Gateway APIs](apigateway-understanding-xray-traces.md) # Configurazione AWS X-Ray con API Gateway REST APIs In questa sezione puoi trovare informazioni dettagliate su come configurare [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)con API Gateway REST APIs. **Topics** + [Modalità di monitoraggio di X-Ray per API Gateway](#apigateway-tracing-modes) + [Autorizzazioni per il monitoraggio di X-Ray](#set-up-xray-tracing-permissions) + [Abilitazione del monitoraggio tramite X-Ray nella console API Gateway](#apigateway-xray-console-setup) + [Abilitazione del AWS X-Ray tracciamento utilizzando l'API Gateway CLI](#apigateway-xray-cli-setup) ## Modalità di monitoraggio di X-Ray per API Gateway Il percorso di una richiesta nell'applicazione viene tracciato mediante un ID traccia. Una traccia raccoglie tutti i segmenti generati da una singola richiesta, in genere una richiesta HTTP `GET` o `POST`. Per un'API di API Gateway sono disponibili due modalità di monitoraggio: + **Passiva**: questa è l'impostazione predefinita se non hai abilitato il monitoraggio X-Ray su una fase API. Questo approccio significa che l'API di API Gateway viene tracciata solo se X-Ray è stato abilitato in un servizio upstream. + **Attiva**: quando per una fase API di API Gateway si sceglie questa impostazione, API Gateway esegue automaticamente il campionamento delle richieste di invocazione dell'API in base all'algoritmo di campionamento specificato da X-Ray. Quando su una fase il monitoraggio è abilitato in modalità attiva, API Gateway crea un ruolo collegato ai servizi nel tuo account se questo non è già esistente. Il ruolo è denominato `AWSServiceRoleForAPIGateway` e sarà collegato alla policy gestita `APIGatewayServiceRolePolicy`. Per ulteriori informazioni sui ruoli collegati ai servizi, consulta [Utilizzo dei ruoli collegati ai servizi](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). **Nota** X-Ray applica un algoritmo di campionamento per garantire che il monitoraggio avvenga in modo efficiente, continuando allo stesso tempo a fornire un campione rappresentativo delle richieste ricevute dall'API. L'algoritmo di campionamento di default corrisponde a una richiesta al secondo, con il 5% di richieste campionate oltre tale limite. Puoi modificare la modalità di tracciamento per la tua API utilizzando la console di gestione API Gateway, l'API Gateway CLI o AWS un SDK. ## Autorizzazioni per il monitoraggio di X-Ray Quando su una fase è abilitato il monitoraggio tramite X-Ray, API Gateway crea un ruolo collegato ai servizi nel tuo account se questo non è già esistente. Il ruolo è denominato `AWSServiceRoleForAPIGateway` e sarà collegato alla policy gestita `APIGatewayServiceRolePolicy`. Per ulteriori informazioni sui ruoli collegati ai servizi, consulta [Utilizzo dei ruoli collegati ai servizi](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). ## Abilitazione del monitoraggio tramite X-Ray nella console API Gateway Puoi utilizzare la console di Amazon API Gateway per abilitare il monitoraggio in modalità attiva in una fase API. In queste fasi si presuppone che l'API sia già stata distribuita a una fase. 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegli l'API, quindi nel pannello di navigazione principale, seleziona **Fasi**. 1. Nel riquadro **Fasi** scegli una fase. 1. Nella sezione **Log e tracciamento** scegli **Modifica**. 1. Per abilitare il tracciamento X-Ray seleziona **Tracciamento X-Ray** per attivarlo. 1. Scegli **Save changes** (Salva modifiche). Una volta abilitato X-Ray per la fase API, è possibile utilizzare la console di gestione di X-Ray per visualizzare il monitoraggio e le mappe di servizio. ## Abilitazione del AWS X-Ray tracciamento utilizzando l'API Gateway CLI Il comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) seguente crea una fase con tracciamento X-Ray attivo: ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=true ``` L'output sarà simile al seguente: ``` { "tracingEnabled": true, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` Il comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) seguente crea una fase senza tracciamento X-Ray attivo: ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=false ``` L'output sarà simile al seguente: ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente attiva il tracciamento X-Ray per un’API implementata: ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --patch-operations op=replace,path=/tracingEnabled,value=true ``` Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente disattiva il tracciamento X-Ray per un’API implementata: ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --region region \ --patch-operations op=replace,path=/tracingEnabled,value=false ``` L'output sarà simile al seguente: ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533850033, "createdDate": 1533849811, "methodSettings": {} } ``` Una volta abilitato X-Ray per la fase API, utilizzare l'interfaccia a riga di comando di X-Ray per recuperare le informazioni sul monitoraggio. Per ulteriori informazioni, vedere [Utilizzo dell'API X-Ray con la CLI AWS](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial). # Usa le mappe dei AWS X-Ray servizi e traccia le viste con API Gateway In questa sezione sono disponibili informazioni dettagliate sull'utilizzo delle mappe di servizio e delle viste di monitoraggio di [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) con API Gateway. **Topics** + [Esempio di mappa dei servizi di X-Ray](#apigateway-using-xray-maps-active) + [Esempio di visualizzazione del monitoraggio di X-Ray](#apigateway-using-xray-trace-view-active) ## Esempio di mappa dei servizi di X-Ray AWS X-Ray le mappe dei servizi mostrano informazioni sull'API e su tutti i relativi servizi a valle. Quando X-Ray è abilitato per una fase API in API Gateway, sarà possibile visualizzare un nodo nella mappa di servizio che contiene informazioni sul tempo complessivo passato nel servizio API Gateway. Puoi ottenere informazioni dettagliate sullo stato della risposta e un istogramma del tempo di risposta dell'API nel periodo di tempo selezionato. Per l' APIs integrazione con AWS servizi come AWS Lambda Amazon DynamoDB, vedrai più nodi che forniscono metriche prestazionali relative a tali servizi. C'è una mappa di servizio per ogni fase API. L'esempio seguente mostra una mappa di servizio per la fase `test` di un'API denominata `xray`. Quest’API dispone di due integrazioni Lambda. I nodi rappresentano il servizio Gateway API e le due funzioni Lambda. Per una spiegazione dettagliata della struttura della mappa di servizio, consulta [Use the X-Ray trace map](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-servicemap). ![\[Esempio di mappa del servizio di una fase API di API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-xray-servicemap-2.png) La mappa dei servizi può essere ingrandita per mostrare una vista della traccia della fase API. La traccia visualizza informazioni approfondite riguardanti l'API, rappresentate come segmenti e segmenti secondari. Ad esempio, il monitoraggio della mappa di servizio mostrata sopra include i segmenti del servizio Lambda e della funzione Lambda. [Per ulteriori informazioni, consulta e.AWS LambdaAWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html) Se scegli un nodo o un edge su una mappa di servizio di X-Ray, la console di X-Ray mostra un istogramma della distribuzione della latenza. Puoi utilizzare un istogramma della latenza per visualizzare il tempo impiegato da un servizio per completare le richieste. Di seguito è riportato un istogramma della fase dell'API Gateway denominata `xray/test` nella precedente mappa di servizio. Per una spiegazione dettagliata degli istogrammi di distribuzione della latenza, consulta [Use Latency Histograms](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-histograms). ![\[Istogramma X-Ray di una fase API di API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-xray-histogram-1.png) ## Esempio di visualizzazione del monitoraggio di X-Ray Il seguente diagramma mostra una vista del monitoraggio generato per l’API di esempio descritta in precedenza, con una funzione di backend Lambda. Viene mostrata una richiesta metodo API andata a buon fine con codice di risposta pari a 200. Per una spiegazione dettagliata delle viste di traccia, consulta [View traces and trace details](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-traces). ![\[API Gateway con monitoraggio in modalità attiva abilitato\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-xray-traceview-1.png) # Configurazione delle regole AWS X-Ray di campionamento per API Gateway APIs Puoi utilizzare la AWS X-Ray console o l'SDK per configurare le regole di campionamento per la tua API Amazon API Gateway. Una regola di campionamento specifica le richieste che X-Ray deve registrare per l'API. Personalizzando le regole di campionamento è possibile controllare la quantità di dati da registrare e modificare immediatamente il campionamento senza dover cambiare o ridistribuire il codice. Prima di specificare le regole di campionamento di X-Ray, leggere i seguenti argomenti nella Guida per gli sviluppatori di X-Ray: + [Configurazione delle regole di campionamento](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling) + [Utilizzo delle regole di campionamento con l'API X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-sampling) **Topics** + [Valori delle opzioni della regola di campionamento a raggi X per API Gateway APIs](#apigateway-xray-sampling-rule-options) + [Esempi di regole di campionamento di X-Ray](#apigateway-xray-sampling-rules-examples) ## Valori delle opzioni della regola di campionamento a raggi X per API Gateway APIs Le seguenti opzioni di campionamento di X-Ray sono rilevanti per API Gateway. I valori di stringa possono utilizzare caratteri jolly per corrispondere a un solo carattere (?) o a zero o più caratteri (\$1). Per ulteriori informazioni, compresa una spiegazione dettagliata di come vengono utilizzate le impostazioni del **reservoir** e della **frequenza**, consulta [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). + **Nome regola** (stringa): un nome univoco per la regola. + **Priorità** (numero intero compreso tra 1 e 9999): la priorità della regola di campionamento. I servizi valutano le regole in ordine crescente di priorità e prendono una decisione sul campionamento in base alla prima regola corrispondente. + **Riserva** (numero intero non negativo): un numero fisso di richieste che rispettano il filtro da analizzare ogni secondo, prima di applicare la percentuale fissa. Il reservoir non viene utilizzato direttamente dai servizi, ma si applica a tutti i servizi che utilizzano la regola nel loro complesso. + **Percentuale** (numero tra 0 e 100): la percentuale di richieste che rispettano il filtro da analizzare dopo l'esaurimento della riserva. + **Nome servizio** (stringa): nome della fase API, nel formato ***\$1api-name\$1*/*\$1stage-name\$1***. Ad esempio, se si dovesse distribuire l'API di [PetStore](api-gateway-create-api-from-example.md)esempio in una fase denominata`test`, il valore del **nome del servizio** da specificare nella regola di campionamento sarebbe. **pets/test** + **Tipo servizio** (stringa): per un'API di API Gateway è possibile specificare sia **AWS::ApiGateway::Stage** che **AWS::ApiGateway::\$1**. + **Host** (stringa): il nome host ricavato dall'intestazione HTTP host. Per la corrispondenza a tutti i nome host, va impostato su **\$1**. Si può anche specificare un nome host completo o parziale di corrispondenza, ad esempio **api.example.com** o **\$1.example.com**. + **Resource ARN (ARN risorsa)** (stringa): l'ARN della fase API, ad esempio **arn:aws:apigateway:*region*::/restapis/*api-id*/stages/*stage-name***. Il nome di fase si può ricavare dalla console, dall'interfaccia a riga di comando o dall'API di API Gateway. Per ulteriori informazioni sui formati degli ARN, consulta [Riferimenti generali di Amazon Web Services](https://docs.aws.amazon.com/general/latest/gr/). + **Metodo HTTP** (stringa): il metodo da campionare, ad esempio **GET**. + **URL path** (Percorso URL) (stringa): il percorso dell'URL della richiesta. + (opzionale) **Attributi** (chiave e valore): intestazioni provenienti dalla richiesta HTTP originale, ad esempio **Connection**, **Content-Length** o **Content-Type**. Ogni valore dell'attributo può contenere fino a 32 caratteri. ## Esempi di regole di campionamento di X-Ray **Esempio 1 di regola di campionamento** Questa regola campiona tutte le richieste `GET` per l'API `testxray` nella fase `test`. + **Nome regola — ****test-sampling** + **Priorità — ****17** + **Dimensioni riserva — ****10** + **Percentuale fissa — ****10** + **Nome servizio — ****testxray/test** + **Tipo servizio — ****AWS::ApiGateway::Stage** + **Metodo HTTP — ****GET** + **ARN risorsa — ****\$1** + **Host — ****\$1** **Esempio 2 di regola di campionamento** Questa regola campiona tutte le richieste `testxray` per l'API nella fase `prod`. + **Nome regola — ****prod-sampling** + **Priorità — ****478** + **Dimensioni riserva — ****1** + **Percentuale fissa — ****60** + **Nome servizio — ****testxray/prod** + **Tipo servizio — ****AWS::ApiGateway::Stage** + **Metodo HTTP — ****\$1** + **ARN risorsa — ****\$1** + **Host — ****\$1** + **Attributi** — **\$1\$1** # AWS X-Ray tracce per Amazon API Gateway APIs Questa sezione illustra i segmenti di AWS X-Ray traccia, i sottosegmenti e altri campi di traccia per Amazon API Gateway. APIs Prima di leggere questa sezione, rivedere i seguenti argomenti nella Guida per gli sviluppatori di X-Ray: + [Usa un Console di gestione AWS](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html) + [Documenti sui segmenti di X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments) + [Concetti](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts) **Topics** + [Esempi di oggetti di monitoraggio per un'API di API Gateway](#apigateway-understanding-xray-traces-example-segments) + [Comprendere la traccia](#apigateway-understanding-xray-traces-segments) ## Esempi di oggetti di monitoraggio per un'API di API Gateway Questa sezione illustra alcuni degli oggetti visibili in un monitoraggio di un'API di API Gateway. **Annotazioni** Le annotazioni possono essere visualizzate nei segmenti e nei segmenti secondari. Servono da espressioni di filtro nelle regole di campionamento per filtrare le tracce. Per ulteriori informazioni, consulta [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). Di seguito è riportato un esempio di un oggetto `annotations`, in cui una fase API è identificata dall'ID dell'API e dal nome della fase API: ``` "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" } ``` Per ulteriori informazioni sulle annotazioni, consulta **X-Ray segment documents** e scegli **Annotations** in [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments). **AWS dati relativi alle risorse** L'oggetto `aws` viene visualizzato solo nei segmenti. Di seguito è riportato l'esempio di un oggetto `aws` corrispondente alla regola di campionamento predefinita. Per una spiegazione dettagliata delle regole di campionamento, consulta [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). ``` "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } } ``` Per ulteriori informazioni sull'oggetto `aws`, consulta **X-Ray segment documents** e **AWS resource data** in [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments). ## Comprendere la traccia Di seguito è riportato un segmento di monitoraggio per una fase dell'API Gateway. Per una spiegazione dettagliata dei campi che compongono il segmento di traccia, consulta [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments). ``` { "Document": { "id": "a1b2c3d4a1b2c3d4", "name": "testxray/dev", "start_time": 1533928226.229, "end_time": 1533928226.614, "metadata": { "default": { "extended_request_id": "abcde12345abcde=", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "http": { "request": { "url": "https://example.com/dev?username=demo&message=hellofromdemo/", "method": "GET", "client_ip": "192.0.2.0", "x_forwarded_for": true }, "response": { "status": 200, "content_length": 0 } }, "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" }, "trace_id": "1-a1b2c3d4-a1b2c3d4a1b2c3d4a1b2c3d4", "origin": "AWS::ApiGateway::Stage", "resource_arn": "arn:aws:apigateway:us-east-1::/restapis/a1b2c3d4e5/stages/dev", "subsegments": [ { "id": "abcdefgh12345678", "name": "Lambda", "start_time": 1533928226.233, "end_time": 1533928226.6130002, "http": { "request": { "url": "https://example.com/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:xray123/invocations", "method": "GET" }, "response": { "status": 200, "content_length": 62 } }, "aws": { "function_name": "xray123", "region": "us-east-1", "operation": "Invoke", "resource_names": [ "xray123" ] }, "namespace": "aws" } ] }, "Id": "a1b2c3d4a1b2c3d4" } ```