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á. # O Trace Step Functions solicita dados em AWS X-Ray 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. A máquina de estado envia dados de rastreamento ao X-Ray que, então, processa os dados para gerar um mapa de serviço e resumos de rastreamento pesquisáveis. Com o X-Ray ativado para sua máquina de estado, você pode rastrear solicitações conforme elas são executadas no Step Functions, em todas as AWS regiões onde o X-Ray está disponível. Isso fornece uma visão geral detalhada de toda uma solicitação do Step Functions. O Step Functions enviará rastreamentos ao X-Ray para execuções de máquina de estado, mesmo quando um ID de rastreamento não é transmitido por um serviço upstream. Você pode usar um mapa do serviço X-Ray para visualizar a latência de uma solicitação, incluindo quaisquer AWS serviços integrados ao X-Ray. Também é possível configurar regras de amostragem para informar ao X-Ray quais solicitações registrar e com quais taxas de amostragem, de acordo com os critérios especificados. Quando o X-Ray não está ativado para a máquina de estado, e um serviço upstream não passa um ID de rastreamento, o Step Functions não envia rastreamentos ao X-Ray para execuções de máquinas de estado. Entretanto, se o ID de rastreamento for transmitido por um serviço upstream, o Step Functions enviará rastreamentos ao X-Ray para execuções de máquina de estado. Você pode usar AWS X-Ray com Step Functions em regiões onde ambos são suportados. Consulte as páginas de endpoints e cotas do [Step Functions](https://docs.aws.amazon.com/general/latest/gr/step-functions.html) e do [X-Ray](https://docs.aws.amazon.com/general/latest/gr/xray.html) para obter informações sobre o suporte regional para X-Ray e Step Functions. **Cotas combinadas de X-Ray e Step Functions** Você pode adicionar dados a um rastreamento por até sete dias e consultar dados de rastreamento que remontam a trinta dias, o período em que o X-Ray armazena os dados de rastreamento. Os rastreamentos estarão sujeitos às cotas de X-Ray. Além de outras cotas, o X-Ray fornece um tamanho mínimo de rastreamento garantido de 100 KiB para máquinas de estado do Step Functions. Se mais de 100 KiB de dados de rastreamento forem fornecidos ao X-Ray, isso poderá resultar em um rastreamento congelado. Consulte a seção de service quotas da página [Endpoints e cotas do X-Ray](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray) para obter mais informações sobre outras cotas do X-Ray. **Importante** O Step Functions não oferece suporte ao rastreamento do X-Ray para as execuções do fluxo de trabalho secundário iniciadas por um [*estado de Mapa distribuído*](state-map-distributed.md) porque é fácil exceder o [Limite de tamanho do documento de rastreamento](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray) para essas execuções. **Topics** + [Definição e configuração](#xray-concept-create) + [Conceitos](#xray-concepts) + [Integrações de serviços](#xray-concept-integrations) + [Como visualizar o console do X-Ray](#xray-concept-tracing-details) + [Como visualizar informações de rastreamento do X-Ray para o Step Functions](#concepts-xray-tracing-events) + [Rastreamentos](#concepts-xray-traces) + [Mapa de serviço](#concepts-xray-tracing-overview) + [Segmentos e subsegmentos](#concepts-xray-tracing-segments) + [Analytics](#concepts-xray-tracing-analytics) + [Configuração](#concepts-xray-tracing-config) + [E se não houver dados no mapa de rastreamento ou no mapa de serviço?](#concepts-xray-troubleshooting) ## Definição e configuração ### Ative o rastreamento do X-Ray ao criar uma máquina de estado Você pode ativar o rastreamento do X-Ray ao criar uma nova máquina de estado selecionando **Ativar rastreamento do X-Ray** na página **Especificar detalhes**. 1. Abra o [console do Step Functions](https://console.aws.amazon.com/states/home) e clique em **Criar máquina de estado**. 1. Na página **Escolher método de criação**, escolha uma opção apropriada para criar a máquina de estado. Se você escolher **Executar um projeto de amostra**, não poderá ativar o rastreamento do X-Ray durante a criação da máquina de estado e precisará ativar o rastreamento do X-Ray após a criação da máquina de estado. Para obter mais informações sobre como ativar o X-Ray em uma máquina de estado existente, consulte [Ativar o X-Ray em uma máquina de estado existente](#xray-concept-enable-existing). Escolha **Próximo**. 1. Na página **Especificar detalhes**, configure a máquina de estado. 1. Escolha **Habilitar rastreamento do X-Ray**. A máquina de estado do Step Functions agora enviará rastreamentos ao X-Ray para execuções de máquinas de estado. **nota** Se você optar por usar um perfil do IAM existente, você deverá garantir que as gravações no X-Ray sejam permitidas. Para ter mais informações sobre as permissões necessárias, consulte o tópico a seguir. ### Políticas do IAM usadas AWS X-Ray em Step Functions Para habilitar o rastreamento do X-Ray, você precisará de uma política do IAM com permissões adequadas. Se a máquina de estado usa outros serviços integrados, podem ser necessárias políticas adicionais do IAM. Veja as políticas do IAM para suas integrações de serviços específicas. Para habilitar o rastreamento do X-Ray para uma máquina de estado existente, será necessário garantir a adição de uma política com permissões suficientes. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets" ], "Resource": [ "*" ] } ] } ``` ### Ativar o X-Ray em uma máquina de estado existente Para ativar o X-Ray em uma máquina de estado existente: 1. No [console do Step Functions](https://console.aws.amazon.com/states/home), selecione a máquina de estado para a qual você deseja ativar o rastreamento. 1. Escolha **Editar**. 1. Escolha **Ativar rastreamento do X-Ray**. Você verá uma notificação informando que talvez seja necessário fazer alterações adicionais. **nota** Ao ativar o X-Ray para uma máquina de estado existente, você terá que se certificar de que tem uma política do IAM com permissões suficientes para que o X-Ray execute rastreamentos. Você pode adicionar uma manualmente ou gerar uma. Para obter mais informações, consulte a seção Política do IAM para o [Políticas do IAM usadas AWS X-Ray em Step Functions](#xray-iam). 1. (Opcional) Gere automaticamente um novo perfil para a máquina de estado a fim de incluir permissões do X-Ray. 1. Escolha **Salvar**. ### Configurar rastreamento do X-Ray para o Step Functions Quando você executa pela primeira vez uma máquina de estado com o X-Ray Tracing ativado, ela usa os valores de configuração padrão para o X-Ray Tracing. AWS X-Ray não coleta dados para cada solicitação enviada a um aplicativo. Em vez disso, ele coleta dados para um número estatisticamente significativo de solicitações. O padrão é registrar a primeira solicitação a cada segundo e cinco por cento de todas as solicitações adicionais. Uma solicitação por segundo é o *reservatório*. Isso garante que pelo menos um rastreamento seja registrado a cada segundo à medida que o serviço atende às solicitações. Cinco por cento é a *taxa* segundo a qual as solicitações adicionais, além do tamanho de reservatório, são amostradas. Para evitar cobranças incorridas para o serviço quando você está começando a usá-lo, a taxa de amostragem padrão é conservadora. Você pode configurar o X-Ray para modificar a regra de amostragem padrão e configurar regras adicionais que aplicam a amostragem com base nas propriedades do serviço ou da solicitação. Por exemplo, talvez você queira desativar a amostragem e rastrear todas as solicitações de chamadas que modificam o estado, o identificador Contas da AWS ou as transações. Para chamadas somente leitura de alto volume, como a sondagem de plano de fundo, as verificações de integridade ou a manutenção da conexão, você pode coletar amostras a uma taxa baixa e ainda obter dados suficientes para observar quaisquer problemas que ocorram. Para configurar uma regra de amostragem para a máquina de estado: 1. Acesse o [console do X-Ray](https://console.aws.amazon.com/xray/home). 1. Escolha **Amostragem**. 1. Para criar uma regra, escolha **Criar regra de amostragem**. Para editar uma regra, escolha o nome de uma regra. Para excluir uma regra, escolha uma regra e use o menu **Actions (Ações)** para excluí-la. Algumas partes das regras de amostragem existentes, como o nome e a prioridade, não podem ser alteradas. Em vez disso, adicione ou clone uma regra existente, faça as alterações desejadas e use a nova regra. Para obter informações detalhadas sobre as regras de amostragem do X-Ray e como configurar os vários parâmetros, consulte [Configurando regras de amostragem no console do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html). ### Integrar serviços upstream Para integrar a execução dos fluxos de trabalho do Step Functions, como fluxos de trabalho padrão, Synchronous e padrão, com um serviço upstream, você precisa definir o `traceHeader`. Isso é feito automaticamente para você se você estiver usando uma API HTTP no API Gateway. No entanto, se você estiver usando uma função Lambda, and/or um SDK, precisará definir você mesmo as chamadas `traceHeader` on the [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)ou [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)API. É necessário especificar o formato `traceHeader` como `\p{ASCII}∗`. Além disso, para permitir que o Step Functions use o mesmo ID de rastreamento, você deve especificar o formato como `Root={TRACE_ID};Sampled={1 or 0}`. Se você estiver usando uma função do Lambda, substitua o `TRACE_ID`pelo ID de rastreamento no segmento atual e defina o campo Amostragem como `1` se o modo de amostragem for true e `0` se o modo de amostragem for false. Fornecer o ID de rastreamento nesse formato garante que você obtenha um rastreamento completo. Veja a seguir um exemplo escrito em Python para mostrar como especificar o `traceHeader`. ``` state_machine = config.get_string_paramter("STATE_MACHINE_ARN") if (xray_recorder.current_subsegment() is not None and xray_recorder.current_subsegment().sampled) : trace_id = "Root={};Sampled=1".format( xray_recorder.current_subsegment().trace_id ) else: trace_id = "Root=not enabled;Sampled=0" LOGGER.info("trace %s", trace_id) # execute it response = states.start_sync_execution( stateMachineArn=state_machine, input=event['body'], name=context.aws_request_id, traceHeader=trace_id ) LOGGER.info(response) ``` **X-Ray rastreamento no cabeçalho ou na carga** Para X-Ray rastreamentos, todos os AWS serviços usam o `X-Amzn-Trace-Id` cabeçalho da solicitação HTTP. Usar o cabeçalho é o mecanismo preferido para identificar um rastreamento. `StartExecution` e as operações de API `StartSyncExecution` também podem usar `traceHeader` no do corpo da carga útil da solicitação. Se **ambas as** fontes forem fornecidas, Step Functions usará o **valor do cabeçalho** (preferencial) sobre o valor no corpo da solicitação. ## Conceitos ### O console do X-Ray No AWS X-Ray console, você pode visualizar mapas e rastreamentos de serviços para solicitações que seus aplicativos atendem quando o X-Ray está habilitado para sua máquina de estado. Consulte [Como visualizar o console do X-Ray](#xray-concept-tracing-details) para obter informações sobre como acessar o console do X-Ray para execuções de máquina de estado. Para obter informações detalhadas sobre o console do X-Ray, consulte a [documentação do console do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html). ### Segmentos, subsegmentos e rastreamentos Um **segmento** registra informações sobre uma solicitação na máquina de estado. Ele contém informações como o trabalho que a máquina de estado executa e também pode conter **subsegmentos** com informações sobre chamadas downstream. Um **rastreamento** coleta todos os segmentos gerados por uma única solicitação. ### Amostragem Para garantir um rastreamento eficiente e fornecer uma amostra representativa das solicitações atendidas pela aplicação, o X-Ray aplica um algoritmo de **amostragem** para determinar quais solicitações são rastreadas. Isso pode ser alterado editando as regras de amostragem. ### Metrics Para a máquina de estado, o X-Ray medirá o tempo de invocação, o tempo de transição de estado, o tempo geral de execução do Step Functions e as variações desse tempo de execução. Essas informações podem ser acessadas por meio do console do X-Ray. ### Analytics O console do AWS X-Ray Analytics é uma ferramenta interativa para interpretar dados de rastreamento. É possível refinar o conjunto de dados ativo com filtros cada vez mais granulares clicando nos gráficos e nos painéis de métricas e campos que estão associados ao conjunto de rastreamentos atual. É possível analisar a performance da máquina de estado, além de localizar e identificar problemas de performance. Para obter informações detalhadas sobre a análise de X-Ray, consulte [Interação com o console do AWS X-Ray Analytics](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-analytics.html) ## Integrações de serviços do Step Functions e X-Ray Alguns dos AWS serviços que se integram ao Step Functions oferecem integração com AWS X-Ray a adição de um cabeçalho de rastreamento às solicitações, a execução do daemon X-Ray ou a tomada de decisões de amostragem e o upload de dados de rastreamento para o X-Ray. Outros devem ser instrumentados usando o AWS X-Ray SDK. Alguns ainda não oferecem suporte à integração com o X-Ray. A integração do X-Ray é necessária para fornecer dados de rastreamento completos ao usar uma integração de serviços com o Step Functions ### Suporte nativo ao X-Ray As integrações de serviços com suporte nativo ao X-Ray incluem: + [Amazon Simple Notification Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html) + [Amazon Simple Queue Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html) + [AWS Lambda](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html) + AWS Step Functions ### Instrumentação necessária Integrações de serviços que exigem [instrumentação do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html): + Amazon Elastic Container Service + AWS Batch + AWS Fargate ### Somente rastreamento do lado do cliente Outras integrações de serviço não são compatíveis com rastreamentos do X-Ray. No entanto, os rastreamentos do lado do cliente ainda podem ser coletados: + Amazon DynamoDB + Amazon EMR + SageMaker Inteligência Artificial da Amazon + AWS CodeBuild + AWS Glue ## Como visualizar o console do X-Ray O X-Ray recebe dados de serviços como segmentos. Em seguida, o X-Ray agrupa segmentos que tenham uma solicitação em comum em rastreamentos. O X-Ray processa os rastreamentos para gerar um gráfico de serviço que apresenta uma representação visual da aplicação. Depois de iniciar a execução da máquina de estado, você pode visualizar os rastreamentos do X-Ray escolhendo o link do **mapa de rastreamento do X-Ray** na seção **Detalhes da execução**. Depois de ativar o X-Ray para a máquina de estado, as informações de rastreamento das execuções podem ser visualizadas no console do X-Ray. ## Como visualizar informações de rastreamento do X-Ray para o Step Functions As seguintes etapas ilustram o tipo de informação que você pode ver no console depois de ativar o X-Ray e realizar uma execução. São mostrados rastreamentos do X-Ray para o projeto de amostra [Criar um exemplo de padrão de retorno de chamada com o Amazon SQS, o Amazon SNS e o Lambda](callback-task-sample-sqs.md). ## Rastreamentos Depois que uma execução é concluída, você poderá navegar até o console do X-Ray, onde verá a página **Rastreamentos** do X-Ray. Isso exibe uma visão geral do mapa de serviços, bem como informações de rastreamento e segmento para a máquina de estado. ![\[Captura de tela ilustrativa de rastreamentos do X-Ray de uma máquina de estado.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/xray-tracing-overview.png) ## Mapa de serviço O mapa de serviço no console do X-Ray ajuda a identificar serviços nos quais estejam ocorrendo erros, nos quais haja conexões com alta latência ou ver rastreamentos para solicitações que foram malsucedidas. ![\[Captura de tela ilustrativa com foco no mapa do serviço em rastreamentos do X-Ray.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/xray-tracing-servicemap.png) No mapa de rastreamento, você 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. Aqui, o nó `WaitForCallBack` foi selecionado e você pode ver informações adicionais sobre o status de execução e resposta. ![\[Exemplos de detalhe de um nó de rastreamento do X-Ray.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/xray-tracing-servicemap-detail.png) Você pode ver como o mapa de serviço do X-Ray se correlaciona com a máquina de estado. Há um nó de mapa de serviço para cada integração de serviço que é chamado pelo Step Functions, desde que ele seja compatível com o X-Ray. ![\[Exemplo de representação gráfica da máquina de estado que está sendo rastreada.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/sample-callback-example.png) ## Segmentos e subsegmentos Um **rastreamento** coleta todos os **segmentos** gerados por uma única solicitação. Cada segmento fornece o nome do recurso, os detalhes sobre a solicitação e os detalhes sobre o trabalho realizado. Na página **Rastreamentos**, você pode ver os segmentos e, se expandidos, os subsegmentos correspondentes. Você pode escolher um segmento ou subsegmento para ver informações detalhadas sobre ele. Você verá um segmento diferente para cada nó no mapa de serviço. ![\[Exemplo de captura de tela de segmentos e subsegmentos de uma máquina de estado.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/xray-tracing-segments.png) Escolher um segmento fornece o nome do recurso, os detalhes sobre a solicitação e os detalhes sobre o trabalho realizado. Um segmento pode dividir os dados sobre o trabalho feito em subsegmentos. A escolha de um subsegmento mostra informações e detalhes de temporização granulares. Um subsegmento pode conter detalhes adicionais sobre uma chamada para um AWS serviço, uma API HTTP externa ou um banco de dados SQL. ## Analytics O console do AWS X-Ray **Analytics** é uma ferramenta interativa para interpretar dados de rastreamento. Você pode usar isso para entender mais facilmente o desempenho da máquina de estado. É possível explorar, analisar e visualizar rastreamentos por meio de grafos interativos de tempo de resposta e de séries temporais para ajudar a localizar problemas de performance e de latência. É possível refinar o conjunto de dados ativo com filtros cada vez mais granulares clicando nos gráficos e nos painéis de métricas e campos que estão associados ao conjunto de rastreamentos atual. ## Configuração Você pode configurar opções de amostragem e criptografia no console do X-Ray. + Escolha **Amostragem** para ver detalhes sobre a taxa de amostragem e a configuração. Você pode alterar as regras de amostragem para controlar a quantidade de dados gravados e modificar o comportamento de amostragem para atender às suas necessidades específicas. + Escolha **Criptografia** para modificar as configurações de criptografia. É possível usar a configuração padrão, na qual o X-Ray criptografa os rastreamentos e os dados em repouso ou, se necessário, escolher uma chave do KMS. As taxas de [AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/) padrão se aplicam no último caso. ## E se não houver dados no mapa de rastreamento ou no mapa de serviço? Se você tiver ativado o X-Ray, mas não conseguir ver nenhum dado no console do X-Ray, verifique se: + Os perfis do IAM estão configurados corretamente para permitir a gravação no X-Ray. + As regras de amostragem permitem a amostragem de dados. + Como pode haver um pequeno atraso até que os perfis do IAM recém-criados ou modificados sejam aplicados, verifique o rastreamento ou os mapas de serviço novamente após alguns minutos. + Se você ver **Data Not Found** no painel X-Ray Traces, verifique [as configurações da sua conta do IAM](https://console.aws.amazon.com/iam/home?#/account_settings) e verifique se ela AWS Security Token Service está ativada para a região pretendida. Para obter mais informações, consulte [Ativação e desativação AWS STSRegião da AWS em um Guia](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) do usuário do *IAM*.