As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Visualizar rastreamentos do X-Ray no Step Functions
Neste tutorial, você aprenderá a usar o X-Ray para rastrear erros que ocorrem ao executar uma máquina de estado. Você pode usar o [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) para visualizar os componentes da máquina de estado, identificar gargalos de desempenho e solucionar problemas de solicitações que resultaram em erros. Neste tutorial, você criará várias funções do Lambda que geram erros aleatórios que podem ser rastreados e analisados usando o X-Ray.
O tutorial [Como criar uma máquina de estado Step Functions que usa Lambda](tutorial-creating-lambda-state-machine.md) orienta você na criação de uma máquina de estado que chama uma função do Lambda. Se você concluiu esse tutorial, vá para a [Etapa 2](#create-xray-lambda-state-machine-step-4) e use o perfil do AWS Identity and Access Management (IAM) criado anteriormente.
## Etapa 1: Criar um perfil do IAM para o Lambda
Ambos AWS Lambda AWS Step Functions podem executar código e acessar AWS recursos (por exemplo, dados armazenados em buckets do Amazon S3). Para manter a segurança, você deve permitir que o Lambda e o Step Functions acessem esses recursos.
O Lambda exige que você atribua uma função AWS Identity and Access Management (IAM) ao criar uma função Lambda, da mesma forma que o Step Functions exige que você atribua uma função do IAM ao criar uma máquina de estado.
### Para criar uma função para uso com o Lambda
Para criar uma função vinculada ao serviço, você usa o console do IAM.
**Para criar uma função (console)**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação do console do IAM, escolha **Perfis**. Então, escolha **Criar perfil**.
1. Escolha o tipo de perfil de **serviço da AWS ** e depois selecione **Lambda**.
1. Escolha o caso de uso do **Lambda**. Casos de uso são definidos pelo serviço para incluir a política de confiança exigida pelo serviço. Então, escolha **Próximo: permissões**.
1. Selecione uma ou mais políticas de permissões a serem anexadas à função (por exemplo, `AWSLambdaBasicExecutionRole`). Consulte [Modelo de permissões do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Selecione a caixa ao lado da política que atribui as permissões que você deseja que a função tenha e, em seguida, escolha **Próximo: Revisar**.
1. Insira um nome em **Nome da função**.
1. (Opcional) Em **Descrição da função**, edite a descrição para a nova função vinculada ao serviço.
1. Reveja a função e escolha **Criar função**.
## Etapa 2: Criar uma função do Lambda
A função do Lambda gerará erros aleatoriamente ou atingirá o tempo limite, produzindo dados de exemplo para visualização no X-Ray.
**Importante**
Certifique-se de que sua função Lambda esteja na mesma AWS conta e em sua máquina Região da AWS de estado.
1. Abra o [console do Lambda](https://console.aws.amazon.com/lambda/home) e clique em **Criar função**.
1. Na seção **Criar função**, selecione **Criar do zero**.
1. Na seção **Informações básicas**, configure a função do Lambda:
1. Em **Function name** (Nome da função), insira `TestFunction1`.
1. Em **Runtime**, selecione **Node.js 18.x**.
1. Em **Role (Função)**, selecione **Choose an existing role (Escolher uma função existente)**.
1. Em **Função existente**, selecione [a função do Lambda que você criou anteriormente](#create-xray-lambda-state-machine-to-create-a-role-for-use-with-lambda).
**nota**
Se o perfil do IAM que você criou não aparecer na lista, será necessário esperar alguns minutos até que ele seja exibido no Lambda.
1. Escolha a opção **Criar função**.
Ao criar a função do Lambda, anote o nome do recurso da Amazon (ARN) exibido no canto superior direito da página. Por exemplo:
```
arn:aws:lambda:region:123456789012:function:TestFunction1
```
1. Copie o código a seguir para a função Lambda na seção **Código da função** da ***TestFunction1***página.
```
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 }
};
```
Esse código cria falhas programadas aleatoriamente que serão usadas para gerar exemplos de erros na máquina de estado que podem ser visualizados e analisados usando rastreamentos do X-Ray.
1. Escolha **Salvar**.
## Etapa 3: Criar mais duas funções do Lambda
Crie mais duas funções do Lambda.
1. Repita a Etapa 2 para criar mais duas funções do Lambda. Em **Nome da função** da primeira função, insira `TestFunction2`. Em **Nome da função** da segunda função, insira `TestFunction3`.
1. No console do Lambda, verifique se agora são exibidas três funções do Lambda, `TestFunction1`, `TestFunction2` e `TestFunction3`.
## Etapa 4: Criar uma máquina de estado
Nesta etapa, você usará o [console do Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/) para criar uma máquina de estado com três estados `Task`. Cada estado `Task` fará referência a uma das três funções do Lambda.
1. Abra o [console do Step Functions](https://console.aws.amazon.com/states/home). No menu, selecione **Máquinas de estado** e, em seguida, selecione **Criar máquina de estado**.
**Importante**
[Certifique-se de que sua máquina de estado esteja na mesma AWS conta e região das funções Lambda que você criou anteriormente nas [etapas 2 e 3](#create-xray-lambda-state-machine-step-2).](#create-xray-lambda-state-machine-step-3)
1. Selecione **Criar do zero**.
1. Nomeie sua máquina de estado e clique em **Continuar** para editá-la no Workflow Studio.
1. Neste tutorial, você escreverá a definição da [Amazon States Language](concepts-amazon-states-language.md) (ASL) da máquina de estado no [Editor de código](workflow-studio.md#wfs-interface-code-editor). Para isso, clique em **Código**.
1. Remova o código clichê existente e cole o código a seguir. Na definição do estado da tarefa, lembre-se de substituir o exemplo ARNs pelas funções ARNs do Lambda que você criou.
```
{
"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"
}
}
}
```
Essa é uma descrição da máquina de estado usando a Amazon States Language. Ela define três estados `Task` chamados `CallTestFunction1`, `CallTestFunction2` e `CallTestFunction3`. Cada uma chama uma das três funções do Lambda. Para obter mais informações, consulte [Estrutura da máquina de estado](statemachine-structure.md).
1. Especifique um nome para a máquina de estado. Para fazer isso, escolha o ícone de edição ao lado do nome padrão da máquina de estado de **MyStateMachine**. Em seguida, em **Configuração da máquina de estado**, insira um nome na caixa **Nome da máquina de estado**.
Para este tutorial, insira o nome **TraceFunctions**.
1. (Opcional) Em **Configuração da máquina de estado**, especifique outras configurações do fluxo de trabalho, como o tipo de máquina de estado e a função de execução.
Para este tutorial, em **Configurações adicionais**, selecione **Ativar rastreamento do X-Ray**. Mantenha todas as outras seleções padrão nas **configurações da máquina de estado**.
Se você [já criou um perfil do IAM](procedure-create-iam-role.md) com as permissões corretas para a máquina de estado e deseja usá-lo, em **Permissões**, clique em **Escolher um perfil existente** e selecione uma função na lista. Ou selecione **Inserir um ARN de função** e forneça o ARN para esse perfil do IAM.
1. Na caixa de diálogo **Confirmar criação do perfil**, selecione **Confirmar** para continuar.
Você também pode escolher **Exibir configurações do perfil** para voltar às **Configurações da máquina de estado**.
**nota**
Se você excluir o perfil do IAM criado pelo Step Functions, não será possível recriá-lo posteriormente. Da mesma forma, se você modificar a função (por exemplo, removendo o Step Functions das entidades principais na política do IAM), o Step Functions não poderá restaurar as configurações originais dela posteriormente.
## Etapa 5: Executar a máquina de estado
As execuções de máquinas de estado são instâncias em que o fluxo de trabalho é executado para a realização de tarefas.
1. Na ***TraceFunctions***página, escolha **Iniciar execução**.
A página **New execution** é exibida.
1. Na caixa de diálogo **Iniciar execução**, faça o seguinte:
1. (Opcional) Insira um nome de execução personalizado para substituir o padrão gerado.
**Nomes e registro em log não ASCII**
O Step Functions aceita nomes de máquina de estado, execuções, atividades e rótulos que contenham caracteres não ASCII. Como esses caracteres impedirão que a Amazon CloudWatch registre dados, recomendamos usar somente caracteres ASCII para que você possa acompanhar as métricas do Step Functions.
1. Selecione **Iniciar execução**.
1. O console do Step Functions direciona você para uma página em que o título é o ID da execução. Essa página é conhecida como página de *Detalhes da execução*. Nesta página, você pode revisar os resultados da execução à medida que a execução avança ou após a conclusão.
Para revisar os resultados da execução, escolha estados individuais na **Exibição em gráfico** e, em seguida, escolha as guias individuais no painel [Detalhes da etapa](concepts-view-execution-details.md#exec-details-intf-step-details) para visualizar os detalhes de cada estado, incluindo entrada, saída e definição, respectivamente. Para obter detalhes sobre as informações de execução que você pode visualizar na página *Detalhes da execução*, consulte [Visão geral dos detalhes da execução](concepts-view-execution-details.md#exec-details-interface-overview).
Execute várias execuções (pelo menos três).
1. Depois que as execuções terminarem, acesse o link do **mapa de rastreamento do X-Ray**. Você pode visualizar o rastreamento enquanto a execução ainda está em andamento, porém, é interessante ver primeiro os resultados da execução antes de visualizar o mapa de rastreamento do X-Ray.
1. Visualize o mapa de serviço para identificar onde estão ocorrendo erros, conexões com alta latência ou rastreamentos de solicitações com erros. Neste exemplo, você pode ver quanto tráfego cada função está recebendo. A `TestFunction2` foi chamada com mais frequência do que a `TestFunction3` e a `TestFunction1` foi chamada duas vezes mais do que `TestFunction2`.
O mapa de serviço indica a integridade de cada nó atribuindo cores a ele com base no índice de chamadas bem-sucedidas em relação a erros e falhas:
+ **Verde** para chamadas bem-sucedidas
+ **Vermelho** para falhas do servidor (erros da série 500)
+ **Amarelo** para erros de clientes (erros da série 400)
+ **Roxo** para erros de controle de utilização (429, muitas solicitações)
![\[Exemplo de captura de tela ilustrativa de nós de rastreamento do X-Ray para três funções de teste.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/tutorial-xray-service.png)
Você também pode escolher um nó de serviço para visualizar as solicitações desse nó ou uma borda entre dois nós para visualizar as solicitações que percorreram essa conexão.
1. Veja o mapa de rastreamento do X-Ray para ver o que aconteceu em cada execução. A visualização da linha do tempo exibe uma hierarquia de segmentos e subsegmentos. A primeira entrada na lista é o segmento, que representa todos os dados registrados pelo serviço para uma única solicitação. Os subsegmentos estão abaixo do segmento. Este exemplo mostra os subsegmentos registrados pelas funções do Lambda.
![\[Exemplo de captura de tela ilustrativa dos segmentos e subsegmentos da linha do tempo do X-Ray para funções de teste.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/tutorial-xray-trace.png)
Para obter mais informações sobre como entender os rastreamentos do X-Ray e usar o X-Ray com o Step Functions, consulte o [O Trace Step Functions solicita dados em AWS X-Ray](concepts-xray-tracing.md)