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à.
# 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"
}
```