Configurazione AWS X-Ray con le API REST di API Gateway

In questa sezione puoi trovare informazioni dettagliate su come configurare AWS X-Ray con le API REST di API Gateway.

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.

  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.

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. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Scegli l'API, quindi nel pannello di navigazione principale, seleziona Fasi.

3. Nel riquadro Fasi scegli una fase.

4. Nella sezione Log e tracciamento scegli Modifica.

5. Per abilitare il tracciamento X-Ray seleziona Tracciamento X-Ray per attivarlo.

6. Seleziona Salvataggio delle 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

Per utilizzare l'opzione AWS CLI per abilitare il tracciamento X-Ray attivo per una fase API quando create la fase, chiamate il comando create-stage come nell'esempio seguente:

aws apigateway create-stage \
    --rest-api-id {rest-api-id} \
    --stage-name {stage-name} \
    --deployment-id {deployment-id} \
    --region {region} \
    --tracing-enabled=true

Di seguito è riportato un esempio di output per una chiamata che va a buon fine:

{
    "tracingEnabled": true, 
    "stageName": {stage-name}, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": {deployment-id}, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}

Per utilizzare AWS CLI per disabilitare il tracciamento X-Ray attivo per una fase API quando create la fase, chiamate il comando create-stage come nell'esempio seguente:

aws apigateway create-stage \
    --rest-api-id {rest-api-id} \
    --stage-name {stage-name} \
    --deployment-id {deployment-id} \
    --region {region} \
    --tracing-enabled=false

Di seguito è riportato un esempio di output per una chiamata che va a buon fine:

{
    "tracingEnabled": false, 
    "stageName": {stage-name}, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": {deployment-id}, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}

Per utilizzare AWS CLI per abilitare il tracciamento X-Ray attivo per un'API già distribuita, chiamate il comando update-stage come segue:

aws apigateway update-stage \
    --rest-api-id {rest-api-id} \
    --stage-name {stage-name} \
    --patch-operations op=replace,path=/tracingEnabled,value=true

Per utilizzare per AWS CLI disabilitare il tracciamento X-Ray attivo per un'API che è già stata distribuita, chiamate il comando update-stage come nell'esempio seguente:

aws apigateway update-stage \
    --rest-api-id {rest-api-id} \
    --stage-name {stage-name} \
    --region {region} \
    --patch-operations op=replace,path=/tracingEnabled,value=false

Di seguito è riportato un esempio di output per una chiamata che va a buon fine:

{
    "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.