

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à.

# Visualizza X-Ray le tracce in Step Functions

In questo tutorial, imparerai come utilizzare per X-Ray tracciare gli errori che si verificano durante l'esecuzione di una macchina a stati. Puoi utilizzarlo [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) per visualizzare i componenti della tua macchina a stati, identificare i colli di bottiglia nelle prestazioni e risolvere le richieste che hanno provocato un errore. In questo tutorial, creerai diverse funzioni Lambda che producono errori in modo casuale, che potrai quindi tracciare e analizzare utilizzando. X-Ray

Il [Creazione di una macchina a stati Step Functions che utilizza Lambda](tutorial-creating-lambda-state-machine.md) tutorial ti guida nella creazione di una macchina a stati che chiama una funzione Lambda. Se hai completato il tutorial, vai al [ passaggio 2 ](#create-xray-lambda-state-machine-step-4) e usa il ruolo AWS Identity and Access Management (IAM) che hai creato in precedenza.

## Fase 1: Creare un ruolo IAM per Lambda
<a name="create-xray-lambda-state-machine-step-1"></a>

Entrambi AWS Step Functions possono eseguire codice AWS Lambda e accedere alle AWS risorse (ad esempio, ai dati archiviati nei bucket Amazon S3). Per mantenere la sicurezza, devi concedere a Lambda e Step Functions l'accesso a queste risorse.

Lambda richiede l'assegnazione di un ruolo AWS Identity and Access Management (IAM) quando si crea una funzione Lambda, allo stesso modo in cui Step Functions richiede l'assegnazione di un ruolo IAM quando si crea una macchina a stati.

### Per creare un ruolo da utilizzare con Lambda
<a name="create-xray-lambda-state-machine-to-create-a-role-for-use-with-lambda"></a>

Si utilizza la console IAM per creare un ruolo collegato al servizio.

**Per creare un ruolo (console)**

1. Accedi Console di gestione AWS e apri la console IAM all'indirizzo. [ https://console.aws.amazon.com/iam/ ](https://console.aws.amazon.com/iam/)

1. Nel pannello di navigazione della console IAM seleziona **Ruoli**. Quindi seleziona **Create role (Crea ruolo)**.

1. Scegli il tipo **AWS di ** ruolo Service, quindi scegli ** Lambda**.

1. Scegli il caso d'**uso ** Lambda. I casi d'uso sono definiti dal servizio in modo da includere la policy di attendibilità richiesta dal servizio. Quindi scegliere **Next: Permissions (Successivo: Autorizzazioni)**.

1. Scegliere una o più policy di autorizzazione da collegare al ruolo (ad esempio, `AWSLambdaBasicExecutionRole`). Consultare [Modello di autorizzazioni AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).

    Selezionare la casella di controllo accanto alla policy che assegna le autorizzazioni da assegnare al ruolo, quindi scegliere **Next: Review (Successivo: Rivedi)**.

1. Immettere un nome di ruolo in **Role name (Nome ruolo)**.

1. (Facoltativo) In **Role description** (Descrizione ruolo) modifica la descrizione per il nuovo ruolo collegato ai servizi.

1. Verificare il ruolo e quindi scegliere **Create role (Crea ruolo)**.

## Passaggio 2: creazione di una funzione Lambda
<a name="create-xray-lambda-state-machine-step-2"></a>

La tua funzione Lambda genererà errori o timeout in modo casuale, producendo dati di esempio da visualizzare. X-Ray

**Importante**  
Assicurati che la tua funzione Lambda sia associata allo stesso AWS account e alla tua Regione AWS macchina statale.

1. Apri la console [ Lambda ](https://console.aws.amazon.com/lambda/home) e scegli la funzione ** Crea. **

1. Nella sezione **Create function (Crea funzione)**, scegliere **Author from scratch (Crea da zero)**.

1. Nella ** sezione Informazioni ** di base, configura la tua funzione Lambda:

   1. Nel campo **Function name (Nome funzione)**, immettere `TestFunction1`.

   1. Per ** Runtime**, scegli ** Node.js ** 18.x.

   1. Per **Role (Ruolo)** selezionare **Choose an existing role (Scegli un ruolo esistente)**.

   1. Per Ruolo ** esistente**, seleziona [ il ruolo Lambda che hai creato in precedenza. ](#create-xray-lambda-state-machine-to-create-a-role-for-use-with-lambda)
**Nota**  
Se il ruolo IAM che hai creato non appare nell'elenco, potrebbe richiedere ancora alcuni minuti per propagarsi a Lambda.

   1. Scegli **Crea funzione**.

      Dopo che Lambda ha creato la funzione, annota il relativo Amazon Resource Name (ARN) visualizzato sulla pagina. Ad esempio:

      ```
      arn:aws:lambda:{{region}}:123456789012:function:TestFunction1
      ```

1. Copia il codice seguente per la funzione Lambda nella ** sezione ** Function code della pagina. ** {{TestFunction1}} **

   ```javascript
   function getRandomSeconds(max) {
       return Math.floor(Math.random() * Math.floor(max)) * 1000;
   }
   function sleep(ms) {
       return new Promise(resolve => setTimeout(resolve, ms));
   }
   export const handler = async (event) => {
       if(getRandomSeconds(4) === 0) {
           throw new Error("Something went wrong!");
       }   
       let wait_time = getRandomSeconds(5);
       await sleep(wait_time);
       return { 'response': true }
   };
   ```

   Questo codice crea errori temporizzati casualmente, che verranno utilizzati per generare errori di esempio nella macchina a stati che possono essere visualizzati e analizzati mediante tracce. X-Ray 

1. Scegli **Save** (Salva).

## Fase 3: Creare altre due funzioni Lambda
<a name="create-xray-lambda-state-machine-step-3"></a>

Crea altre due funzioni Lambda.

1. Ripeti il passaggio 2 per creare altre due funzioni Lambda. Per la funzione successiva, in Nome ** della funzione**, inserisci`TestFunction2`. Per l'ultima funzione, in Nome ** funzione**, immettere`TestFunction3`.

1. Nella console Lambda, verifica di avere ora tre funzioni Lambda, `TestFunction1``TestFunction2`, e. `TestFunction3`

## Fase 4: Creare una macchina a stati
<a name="create-xray-lambda-state-machine-step-4"></a>

In questo passaggio, utilizzerai la console [ Step Functions ](https://console.aws.amazon.com/states/home?region=us-east-1#/) per creare una macchina a stati con tre `Task` stati. Ogni `Task` stato farà riferimento a una delle tre funzioni Lambda. 

1. Apri la console [ Step Functions](https://console.aws.amazon.com/states/home), scegli ** State machines ** dal menu, quindi scegli ** Create state machine**.
**Importante**  
Assicurati che la tua macchina a stati si trovi nello stesso AWS account e nella stessa regione delle funzioni Lambda che hai creato in precedenza nei [ passaggi 2 ](#create-xray-lambda-state-machine-step-2) e [ 3](#create-xray-lambda-state-machine-step-3).

1. Scegli ** Crea da vuoto**.

1. Assegna un nome alla tua macchina a stati, quindi scegli ** Continua ** per modificare la tua macchina a stati in Workflow Studio.

1. Per questo tutorial, scriverai la definizione [Lingua degli Stati di Amazon](concepts-amazon-states-language.md) (ASL) della tua macchina a stati in. [Editor del codice](workflow-studio.md#wfs-interface-code-editor) Per fare ciò, scegli ** Codice. **

1. Rimuovi il codice standard esistente e incolla il codice seguente. Nella definizione dello stato dell'attività, ricorda di sostituire gli ARN di esempio con gli ARN delle funzioni Lambda che hai creato.

   ```json
   {
     "StartAt": "CallTestFunction1",
     "States": {
       "CallTestFunction1": {
         "Type": "Task",
         "Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function1}}",
         "Catch": [
           {
             "ErrorEquals": [
               "States.TaskFailed"
             ],
             "Next": "AfterTaskFailed"
           }
         ],
         "Next": "CallTestFunction2"
       },
       "CallTestFunction2": {
         "Type": "Task",
         "Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function2}}",
         "Catch": [
           {
             "ErrorEquals": [
               "States.TaskFailed"
             ],
             "Next": "AfterTaskFailed"
           }
         ],
         "Next": "CallTestFunction3"
       },
       "CallTestFunction3": {
         "Type": "Task",
         "Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function3}}",
         "TimeoutSeconds": 5,
         "Catch": [
           {
             "ErrorEquals": [
               "States.Timeout"
             ],
             "Next": "AfterTimeout"
           },
           {
             "ErrorEquals": [
               "States.TaskFailed"
             ],
             "Next": "AfterTaskFailed"
           }
         ],
         "Next": "Succeed"
       },
       "Succeed": {
         "Type": "Succeed"
       },
       "AfterTimeout": {
         "Type": "Fail"
       },
       "AfterTaskFailed": {
         "Type": "Fail"
       }
     }
   }
   ```

   Questa è una descrizione della tua macchina a stati utilizzando Amazon States Language. Definisce tre `Task` stati denominati`CallTestFunction1`, `CallTestFunction2` e`CallTestFunction3`. Ciascuno chiama una delle tre funzioni Lambda. Per ulteriori informazioni, consultare [Struttura di una macchina a stati](statemachine-structure.md).

1. Specifica un nome per la tua macchina a stati. Per fare ciò, scegli l'icona di modifica accanto al nome della macchina a stati predefinita di ** MyStateMachine**. Quindi, nella configurazione della macchina a ** stati**, specificate un nome nella ** casella Nome macchina a ** stato.

   Per questo tutorial, inserisci il nome **TraceFunctions**.

1. (Facoltativo) Nella configurazione della macchina a ** stati**, specificate altre impostazioni del flusso di lavoro, come il tipo di macchina a stati e il relativo ruolo di esecuzione.

   Per questo tutorial, in Configurazione ** aggiuntiva**, scegli ** Abilita X-Ray tracciamento. ** Mantieni tutte le altre selezioni predefinite nelle impostazioni della macchina ** State. **

   Se [ in precedenza hai creato un ruolo IAM ](procedure-create-iam-role.md) con le autorizzazioni corrette per la tua macchina a stati e desideri utilizzarlo, in ** Autorizzazioni**, seleziona ** Scegli un ruolo esistente**, quindi seleziona un ruolo dall'elenco. Oppure seleziona ** Inserisci un ARN per il ruolo ** e quindi fornisci un ARN per quel ruolo IAM.

1. Nella finestra di ** dialogo ** Conferma creazione del ruolo, scegli ** Conferma ** per continuare.

   Puoi anche scegliere ** Visualizza le impostazioni dei ruoli ** per tornare alla configurazione della macchina ** State**.
**Nota**  
Se elimini il ruolo IAM creato da Step Functions, Step Functions non può ricrearlo in un secondo momento. Analogamente, se modifichi il ruolo (ad esempio, rimuovendo Step Functions dai principali nella policy IAM), Step Functions non può ripristinare le impostazioni originali in un secondo momento. 

## Fase 5: Esegui la macchina di stato
<a name="create-xray-lambda-state-machine-step-5"></a>

Le esecuzioni della macchina a stati sono istanze in cui si esegue il flusso di lavoro per eseguire attività.

1. Nella ** {{TraceFunctions}} ** pagina, scegli ** Avvia esecuzione. **

   Viene visualizzata la pagina **New execution (Nuova esecuzione)**.

1. Nella finestra di ** dialogo ** Avvia esecuzione, effettuate le seguenti operazioni:

   1. (Facoltativo) Immettete un nome di esecuzione personalizzato per sovrascrivere il valore predefinito generato.
**Non-ASCII nomi e registrazione**  
Step Functions accetta nomi per macchine a stati, esecuzioni, attività ed etichette che contengono caratteri non ASCII. Poiché tali caratteri impediranno ad Amazon di registrare i dati, consigliamo di utilizzare solo caratteri ASCII in modo CloudWatch da poter tenere traccia delle metriche di Step Functions.

   1. Selezionare **Start execution (Avvia esecuzione)**.

   1. La console Step Functions ti indirizza a una pagina intitolata con il tuo ID di esecuzione. Questa pagina è nota come pagina dei dettagli di * esecuzione. * In questa pagina, puoi esaminare i risultati dell'esecuzione man mano che l'esecuzione procede o al suo completamento.

      Per esaminare i risultati dell'esecuzione, scegli i singoli stati nella vista ** Grafico**, quindi scegli le singole schede [Dettagli del passaggio](concepts-view-execution-details.md#exec-details-intf-step-details) nel riquadro per visualizzare i dettagli di ogni stato, inclusi rispettivamente input, output e definizione. Per i dettagli sulle informazioni sull'esecuzione, è possibile visualizzare nella * pagina Dettagli di * esecuzione, vedere[Panoramica dei dettagli di esecuzione](concepts-view-execution-details.md#exec-details-interface-overview).

      Esegui diverse (almeno tre) esecuzioni.

1. Al termine delle esecuzioni, segui il link della mappa ** di ** X-Ray tracciamento. Puoi visualizzare la traccia mentre un'esecuzione è ancora in esecuzione, ma potresti voler vedere i risultati dell'esecuzione prima di visualizzare la mappa di X-Ray traccia.

1. Visualizza la mappa dei servizi per identificare dove si verificano errori, connessioni con latenza elevata o tracce di richieste non riuscite. In questo esempio, puoi vedere quanto traffico riceve ciascuna funzione. `TestFunction2`è stato chiamato più spesso di`TestFunction3`, ed `TestFunction1` è stato chiamato più del doppio di`TestFunction2`.

   La mappa del servizio indica lo stato di salute di ogni nodo colorandolo in base al rapporto delle chiamate concluse con successo rispetto a errori e malfunzionamenti:
   +  **Verde** per le chiamate concluse con successo 
   +  **Rosso** per i malfunzionamenti del server (errori serie 500) 
   +  **Giallo** per gli errori client (errori serie 400) 
   +  **Viola** per gli errori di superamento dei limiti (429 Too Many Requests)   
![Schermata illustrativa di esempio dei nodi di X-Ray traccia per tre funzioni di test.](https://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/tutorial-xray-service.png)

   Puoi anche scegliere un nodo di servizio per visualizzare le richieste per quel nodo o un bordo tra due nodi per visualizzare le richieste che hanno raggiunto quella connessione. 

1. Visualizza la mappa di X-Ray tracciamento per vedere cosa è successo per ogni esecuzione. La visualizzazione della sequenza temporale mostra una gerarchia di segmenti e sottosegmenti. La prima voce nell'elenco è il segmento, che rappresenta tutti i dati registrati tramite il servizio per una singola richiesta. Sotto il segmento sono presenti i sottosegmenti. Questo esempio mostra i sottosegmenti registrati dalle funzioni Lambda.  
![Schermata di esempio illustrativa dei segmenti e dei sottosegmenti della X-Ray timeline per le funzioni di test.](https://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/tutorial-xray-trace.png)

   Per ulteriori informazioni sulla comprensione delle X-Ray tracce e sull'utilizzo X-Ray con Step Functions, consulta [Dati della richiesta Trace Step Functions in AWS X-Ray](concepts-xray-tracing.md) 