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á. # AWS X-Ray aplicação de amostra **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O aplicativo AWS X-Ray [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray)Sample, disponível em GitHub, mostra o uso do AWS X-Ray SDK para instrumentar chamadas HTTP recebidas, clientes SDK do DynamoDB e clientes HTTP. O aplicativo de amostra é usado CloudFormation para criar tabelas do DynamoDB, compilar código Java na instância e executar o daemon X-Ray sem nenhuma configuração adicional. Consulte o [tutorial do Scorekeep](scorekeep-tutorial.md) para começar a instalar e usar um aplicativo de amostra instrumentado, usando o Console de gerenciamento da AWS ou o. AWS CLI ![\[O Scorekeep usa o AWS X-Ray SDK para instrumentar chamadas HTTP recebidas, clientes SDK do DynamoDB e clientes HTTP\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-flow.png) O exemplo inclui um aplicativo web de front-end, a API chamada e as tabelas do DynamoDB usadas para armazenar os dados. A instrumentação básica com [filtros](xray-sdk-java-filters.md), [plug-ins](xray-sdk-java-configuration.md) e [clientes AWS SDK instrumentados](xray-sdk-java-awssdkclients.md) é mostrada na ramificação do projeto. `xray-gettingstarted` Essa é a ramificação que você implanta no [tutorial de conceitos básicos](scorekeep-tutorial.md). Como essa ramificação inclui apenas os conceitos básicos, você pode compará-la com a ramificação `master` para compreender rapidamente os conceitos básicos. ![\[Service map showing client interaction with Scorekeep container and related Serviços da AWS.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) O aplicativo de amostra mostra a instrumentação básica nesses arquivos: + **Filtro de solicitação HTTP**: [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java) + **AWS Instrumentação do cliente SDK** — [https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle](https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle) [A `xray` ramificação do aplicativo inclui o uso de [anotações [HTTPClient](xray-sdk-java-httpclients.md)](xray-sdk-java-segment.md), [consultas SQL](xray-sdk-java-sqlclients.md), [subsegmentos personalizados](xray-sdk-java-subsegments.md), uma [AWS Lambda](xray-services-lambda.md)função instrumentada e códigos e scripts de inicialização instrumentados.](scorekeep-startup.md) Para oferecer suporte ao login e ao AWS SDK para JavaScript uso do usuário no navegador, a `xray-cognito` filial adiciona o Amazon Cognito para oferecer suporte à autenticação e autorização do usuário. Com as credenciais recuperadas do Amazon Cognito, o aplicativo web também envia dados de rastreamento ao X-Ray para registrar as informações da solicitação do ponto de vista do cliente. O cliente do navegador aparece como seu próprio nó no mapa de rastreamento e grava informações adicionais, incluindo o URL da página que o usuário está visualizando e o ID do usuário. Finalmente, a ramificação `xray-worker` adiciona uma função do Lambda instrumentada em Python que é executada de forma independente e processa os itens com base em uma fila do Amazon SQS. O Scorekeep adiciona um item à fila cada vez que um jogo termina. O trabalhador Lambda, acionado por CloudWatch Eventos, retira itens da fila a cada poucos minutos e os processa para armazenar registros do jogo no Amazon S3 para análise. **Topics** + [Conceitos básicos da aplicação Scorekeep de exemplo](scorekeep-tutorial.md) + [Instrumentando manualmente os clientes do AWS SDK](scorekeep-sdkclients.md) + [Criar subsegmentos adicionais](scorekeep-subsegments.md) + [Gravando anotações, metadados e usuário IDs](scorekeep-annotations.md) + [Instrumentar chamadas HTTP de saída](scorekeep-httpclient.md) + [Instrumentação de chamadas para um banco de dados PostgreSQL](scorekeep-postgresql.md) + [Funções de instrumentação AWS Lambda](scorekeep-lambda.md) + [Instrumentar código de inicialização](scorekeep-startup.md) + [Scripts de instrumentação](scorekeep-scripts.md) + [Instrumentar o cliente do aplicativo web](scorekeep-client.md) + [Usar clientes instrumentais em threads de operador](scorekeep-workerthreads.md) # Conceitos básicos da aplicação Scorekeep de exemplo **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Este tutorial usa a `xray-gettingstarted` ramificação do [aplicativo de amostra Scorekeep](xray-scorekeep.md), usada CloudFormation para criar e configurar os recursos que executam o aplicativo de amostra e o daemon X-Ray no Amazon ECS. O aplicativo usa a estrutura Spring para implementar uma API web JSON e AWS SDK para Java para manter os dados no Amazon DynamoDB. Um filtro de servlet no aplicativo instrumenta todas as solicitações recebidas atendidas pelo aplicativo e um manipulador de solicitações no cliente AWS SDK instrumenta chamadas downstream para o DynamoDB. Você pode seguir este tutorial usando o Console de gerenciamento da AWS ou AWS CLI o. **Topics** + [Pré-requisitos](#xray-gettingstarted-prereqs) + [Instale o aplicativo Scorekeep usando CloudFormation](#xray-gettingstarted-deploy) + [Gerar dados de rastreamento](#xray-gettingstarted-generate-traces) + [Veja o mapa de rastreamento no Console de gerenciamento da AWS](#xray-gettingstarted-console) + [Configuração de notificações do Amazon SNS](#xray-gettingstarted-notifications) + [Explorar o aplicativo de amostra](#xray-gettingstarted-sample) + [Opcional: política de menor privilégio](#xray-gettingstarted-security) + [Limpeza](#xray-gettingstarted-cleanup) + [Próximas etapas](#xray-gettingstarted-nextsteps) ## Pré-requisitos Este tutorial é usado CloudFormation para criar e configurar os recursos que executam o aplicativo de amostra e o daemon X-Ray. Para instalar e executar o tutorial, você deve cumprir os seguintes pré-requisitos: 1. Se você usa um usuário do IAM com permissões limitadas, adicione as seguintes políticas de usuário no [console do IAM](https://console.aws.amazon.com/iam): + `AWSCloudFormationFullAccess`— para acessar e usar CloudFormation + `AmazonS3FullAccess`— para fazer upload de um arquivo de modelo para CloudFormation usar o Console de gerenciamento da AWS + `IAMFullAccess`: para criar os perfis de instância do Amazon ECS e do Amazon EC2 + `AmazonEC2FullAccess`: para criar os recursos do Amazon EC2 + `AmazonDynamoDBFullAccess`: para criar as tabelas do DynamoDB + `AmazonECS_FullAccess`: para criar recursos do Amazon ECS + `AmazonSNSFullAccess`: para criar o tópico do Amazon SNS + `AWSXrayReadOnlyAccess`: para obter permissão para visualizar o mapa de serviço e os rastreamentos no console do X-Ray 1. Para executar o tutorial usando o AWS CLI, [instale a CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) versão 2.7.9 ou posterior e configure [a CLI com o](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) usuário da etapa anterior. Certifique-se de que a região esteja configurada ao configurar o AWS CLI com o usuário. Se uma região não estiver configurada, você precisará anexar `--region AWS-REGION` a cada comando da CLI. 1. O [Git](https://github.com/git-guides/install-git) deve estar instalado para clonar o repositório do aplicativo de exemplo. 1. Use o exemplo de código a seguir para clonar a `xray-gettingstarted` ramificação do repositório Scorekeep: ``` git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted ``` ## Instale o aplicativo Scorekeep usando CloudFormation ------ #### [ Console de gerenciamento da AWS ] **Instale o aplicativo de amostra usando o Console de gerenciamento da AWS** 1. Abra o [console do CloudFormation](https://console.aws.amazon.com/cloudformation/). 1. Escolha **Criar pilha** e selecione **Com novos recursos** no menu suspenso. 1. Na seção **Specify template** (Especificar modelo) escolha **Upload a template file** (Fazer upload de um arquivo de modelo). 1. Selecione **Escolher arquivo**, navegue até a pasta `xray-scorekeep/cloudformation` que foi criada quando você clonou o repositório do Git e escolha o arquivo `cf-resources.yaml`. 1. Escolha **Próximo** para continuar. 1. Insira `scorekeep` na caixa de texto **Nome da pilha** e escolha **Próximo** na parte inferior da página para continuar. Observe que o restante deste tutorial pressupõe que a pilha se chame `scorekeep`. 1. Role até a parte inferior da página **Configurar opções de pilha** e escolha **Próximo** para continuar. 1. Role até a parte inferior da página de **revisão**, escolha a caixa de seleção reconhecendo que CloudFormation pode criar recursos do IAM com nomes personalizados e escolha **Criar** pilha. 1. A CloudFormation pilha agora está sendo criada. O status da pilha será `CREATE_IN_PROGRESS` por cerca de cinco minutos antes de mudar para `CREATE_COMPLETE`. O status será atualizado periodicamente ou você poderá atualizar a página. ------ #### [ AWS CLI ] **Instale o aplicativo de amostra usando o AWS CLI** 1. Navegue até a pasta `cloudformation` do repositório do `xray-scorekeep` que você clonou anteriormente no tutorial: ``` cd xray-scorekeep/cloudformation/ ``` 1. Digite o seguinte AWS CLI comando para criar a CloudFormation pilha: ``` aws cloudformation create-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Espere até que o status da CloudFormation pilha seja`CREATE_COMPLETE`, o que levará cerca de cinco minutos. Use o AWS CLI comando a seguir para verificar o status: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## Gerar dados de rastreamento O aplicativo de amostra inclui um aplicativo Web front-end. Use o aplicativo web para gerar tráfego para a API e enviar dados de rastreamento para o X-Ray. Primeiro, recupere o URL do aplicativo web usando o Console de gerenciamento da AWS ou a AWS CLI: ------ #### [ Console de gerenciamento da AWS ] **Encontre o URL do aplicativo usando o Console de gerenciamento da AWS** 1. Abra o [console do CloudFormation](https://console.aws.amazon.com/cloudformation/). 1. Escolha a pilha `scorekeep` na lista. 1. Escolha a guia **Saídas** na página da pilha `scorekeep` e selecione o link do URL `LoadBalancerUrl` para abrir o aplicativo web. ------ #### [ AWS CLI ] **Encontre o URL do aplicativo usando o AWS CLI** 1. Use o seguinte comando para exibir o URL do aplicativo web: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].Outputs[0].OutputValue" ``` 1. Copie esse URL e abra em um navegador para exibir o aplicativo web Scorekeep. ------ **Usar o aplicativo web para gerar dados de rastreamento** 1. Escolha **Create** para criar um usuário e uma sessão. 1. Digite um **game name**, defina **Rules** para **Tic Tac Toe** e, em seguida, clique em **Create** para criar um jogo. 1. Escolha **Play** para iniciar o jogo. 1. Escolha um bloco para fazer um movimento e alterar o estado do jogo. Cada uma dessas etapas gera solicitações HTTP para a API e chamadas subsequentes para o DynamoDB para ler e gravar dados de usuário, sessão, jogo, movimento e estado. ## Veja o mapa de rastreamento no Console de gerenciamento da AWS Você pode ver o mapa de rastreamento e os traços gerados pelo aplicativo de amostra no X-Ray e nos CloudWatch consoles. ------ #### [ X-Ray console ] **Usar o console do X-Ray** 1. Abra a página do mapa de serviço do [console do X-Ray](https://console.aws.amazon.com/xray/home#/service-map). 1. O console mostra uma representação do gráfico de serviço que o X-Ray gera com base nos dados de rastreamento enviados pelo aplicativo. Ajuste o período do mapa de serviço, se necessário, para garantir que ele exiba todos os rastreamentos desde que você iniciou o aplicativo web. ![\[Período do mapa de rastreamento do X-Ray\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/xray-console-time-period-15-minutes.png) O mapa de serviço mostra o cliente do aplicativo web, a API em execução no Amazon ECS e cada tabela do DynamoDB que o aplicativo usa. Cada solicitação para o aplicativo, até um número máximo configurável de solicitações por segundo, é rastreada quando atinge a API, gera solicitações para serviços subsequentes e é concluída. Você pode escolher qualquer nó no gráfico do serviço para visualizar rastreamentos de solicitações que geraram tráfego nesse nó. No momento, o nó do Amazon SNS é amarelo. Pesquise mais para descobrir o motivo. ![\[Página do mapa de rastreamento do console do X-Ray\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) **Para encontrar a causa do erro** 1. Escolha o nó chamado **SNS**. A página de detalhes de nó será exibida. 1. Selecione **View traces (Visualizar rastreamentos)** para acessar a tela **Trace overview (Visão geral do rastreamento)**. 1. Escolha o rastreamento na **Trace list**. Esse rastreamento não tem um método ou URL porque, em vez de ele ser registrado em resposta a uma solicitação recebida, seu registro foi feito durante o startup. ![\[Escolher um rastreamento da lista de rastreamentos\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-tracelist-sns.png) 1. Escolha o ícone de status de erro no segmento do Amazon SNS na parte inferior da página para abrir a página **Exceções** do subsegmento do SNS. ![\[Escolha o ícone de status de erro para abrir a página Exceções do subsegmento do Amazon SNS\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-timeline-sns-ecs.png) 1. O X-Ray SDK captura automaticamente exceções lançadas pelos clientes instrumentados de SDK da AWS e registra o rastreamento da pilha. ![\[A guia Exceptions (Exceções) mostrando as exceções capturadas e o rastreamento de pilha registrado\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-exception.png) ------ #### [ CloudWatch console ] **Use o CloudWatch console** 1. Abra a página do [mapa de rastreamento X-Ray](https://console.aws.amazon.com/cloudwatch/home#xray:service-map/map) do CloudWatch console. 1. O console mostra uma representação do gráfico de serviço que o X-Ray gera com base nos dados de rastreamento enviados pelo aplicativo. Ajuste o período do mapa de serviço, se necessário, para garantir que ele exiba todos os rastreamentos desde que você iniciou o aplicativo web. ![\[CloudWatch período de tempo do mapa de rastreamento\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/cw-console-service-map-time-period-15-minutes.png) O mapa de serviço mostra o cliente do aplicativo web, a API em execução no Amazon EC2 e cada tabela do DynamoDB que o aplicativo usa. Cada solicitação para o aplicativo, até um número máximo configurável de solicitações por segundo, é rastreada quando atinge a API, gera solicitações para serviços subsequentes e é concluída. Você pode escolher qualquer nó no gráfico do serviço para visualizar rastreamentos de solicitações que geraram tráfego nesse nó. No momento, o nó do Amazon SNS é laranja. Pesquise mais para descobrir o motivo. ![\[Página do mapa de rastreamento do console do X-Ray\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-before-ECS.png) **Para encontrar a causa do erro** 1. Escolha o nó chamado **SNS**. O painel de detalhes do nó SNS é exibido abaixo do mapa. 1. Escolha **Visualizar rastreamentos** para acessar a página **Rastreamentos**. 1. Adicione a parte inferior da página e selecione o rastreamento na lista **Rastreamentos**. Esse rastreamento não tem um método ou URL porque, em vez de ele ser registrado em resposta a uma solicitação recebida, seu registro foi feito durante o startup. ![\[Escolher um rastreamento da lista de rastreamentos\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-cw-tracelist-sns-ecs.png) 1. Escolha o subsegmento do Amazon SNS na parte inferior da linha do tempo dos segmentos e selecione a guia **Exceções** do subsegmento do SNS para visualizar os detalhes da exceção. ![\[Visualizar a guia Exceções para o subsegmento do Amazon SNS\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png) ------ A causa indica que o endereço de e-mail fornecido em uma chamada de `createSubscription` feita na classe `WebConfig` foi inválida. Na próxima seção, corrigiremos isso. ## Configuração de notificações do Amazon SNS O Scorekeep usa o Amazon SNS para enviar notificações quando os usuários concluem um jogo. Quando o aplicativo é iniciado, ele tenta criar uma assinatura para um endereço de e-mail definido em um parâmetro de CloudFormation pilha. Essa chamada está falhando no momento. Configure um e-mail de notificação para habilitar notificações e resolver as falhas destacadas no mapa de serviço. ------ #### [ Console de gerenciamento da AWS ] **Para configurar as notificações do Amazon SNS usando o Console de gerenciamento da AWS** 1. Abra o [console do CloudFormation](https://console.aws.amazon.com/cloudformation/). 1. Escolha o botão de rádio ao lado do nome da pilha `scorekeep` na lista e selecione **Atualizar**. 1. A opção **Usar modelo atual** deve estar selecionada. Clique em **Próximo** na página **Atualizar pilha**. 1. Encontre o parâmetro **E-mail** na lista e substitua o valor padrão por um endereço de e-mail válido. ![\[Atualizar configuração de e-mail\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-cf-email-update.png) 1. Role para o final da página e selecione **Next** (Próximo). 1. Role até a parte inferior da página de **revisão**, escolha a caixa de seleção reconhecendo que CloudFormation pode criar recursos do IAM com nomes personalizados e escolha **Atualizar** pilha. 1. A CloudFormation pilha agora está sendo atualizada. O status da pilha será `UPDATE_IN_PROGRESS` por cerca de cinco minutos antes de mudar para `UPDATE_COMPLETE`. O status será atualizado periodicamente ou você poderá atualizar a página. ------ #### [ AWS CLI ] **Para configurar as notificações do Amazon SNS usando o AWS CLI** 1. Navegue até a pasta `xray-scorekeep/cloudformation/` que você criou anteriormente e abra o arquivo `cf-resources.yaml` em um editor de texto. 1. Encontre o `Default` valor no parâmetro **Email** e altere-o *UPDATE\$1ME* para um endereço de e-mail válido. ``` Parameters: Email: Type: String Default: UPDATE_ME # <- change to a valid abc@def.xyz email address ``` 1. Na `cloudformation` pasta, atualize a CloudFormation pilha com o seguinte AWS CLI comando: ``` aws cloudformation update-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Espere até que o status da CloudFormation pilha seja`UPDATE_COMPLETE`, o que levará alguns minutos. Use o AWS CLI comando a seguir para verificar o status: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ Quando a atualização for concluída, o Scorekeep será reiniciado e criará uma assinatura para o tópico do SNS. Verifique seu e-mail e confirme a assinatura para ver as atualizações quando você concluir um jogo. Abra o mapa de serviço para verificar se as chamadas para o SNS não estão mais falhando. ## Explorar o aplicativo de amostra A aplicativo de exemplo é uma API da web HTTP em Java que é configurada para usar o X-Ray SDK para Java. Quando você implanta o aplicativo com o CloudFormation modelo, ele cria as tabelas do DynamoDB, o Amazon ECS Cluster e outros serviços necessários para executar o Scorekeep no ECS. Um arquivo de definição de tarefas para o ECS é criado por meio de CloudFormation. Esse arquivo define as imagens de contêiner usadas por tarefa em um cluster do ECS. Essas imagens são obtidas do ECR público oficial do X-Ray. A imagem de contêiner da API do Scorekeep tem a API compilada com o Gradle. A imagem de contêiner do front-end do Scorekeep atende ao front-end usando o servidor de proxy nginx. Esse servidor encaminha solicitações para caminhos que começam com /api à API. Para instrumentar solicitações HTTP de entrada, o aplicativo adiciona o `TracingFilter` fornecido pelo SDK. **Example src/main/java/scorekeep/WebConfig.java - filtro de servlet** ``` import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); ... @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } ... ``` Esse filtro envia dados de rastreamento sobre todas as solicitações de entrada que o aplicativo atende, incluindo URL de solicitação, método, status de resposta, horário de início e de término. A aplicativo também faz chamadas subsequentes para o DynamoDB usando o AWS SDK para Java. Para instrumentar essas chamadas, o aplicativo simplesmente usa os submódulos AWS relacionados ao SDK como dependências, e o X-Ray SDK for Java instrumenta automaticamente todos os clientes do SDK. AWS A aplicativo usa o `Docker` para criar o código-fonte na instância com a `Gradle Docker Image` e um arquivo `Scorekeep API Dockerfile` para executar o JAR executável que o Gradle gera no respectivo `ENTRYPOINT`. **Example Exemplo do uso do Docker para criar imagem do Docker por meio do Gradle** ``` docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build ``` **Example Exemplo ENTRYPOINT do Dockerfile** ``` ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ] ``` O arquivo `build.gradle` baixa os submódulos do SDK a partir do Maven durante a compilação declarando-os como dependências. **Example build.gradle -- dependências** ``` ... dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile('org.springframework.boot:spring-boot-starter-test') compile('com.amazonaws:aws-java-sdk-dynamodb') compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") ... } dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0") } } ``` Os submódulos core, AWS SDK e AWS SDK Instrumentor são tudo o que é necessário para instrumentar automaticamente qualquer chamada downstream feita com o SDK. AWS Para retransmitir os dados do segmento bruto para a API do X-Ray, o daemon do X-Ray é necessário para escutar o tráfego na porta UDP 2000. Para fazer isso, o aplicativo executa o daemon do X-Ray em um contêiner que é implantado com o aplicativo Scorekeep no ECS como um *contêiner auxiliar*. Confira o tópico [Daemon do X-Ray](xray-daemon.md) para obter mais informações. **Example Definição do contêiner do daemon do X-Ray em uma definição de tarefa do ECS** ``` ... Resources: ScorekeepTaskDefinition: Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions: ... - Cpu: '256' Essential: true Image: amazon/aws-xray-daemon MemoryReservation: '128' Name: xray-daemon PortMappings: - ContainerPort: '2000' HostPort: '2000' Protocol: udp ... ``` O X-Ray SDK para Java oferece uma classe chamada `AWSXRay`, que fornece o registrador global, um `TracingHandler` que você pode usar para instrumentar seu código. Você pode configurar o gravador global para personalizar o `AWSXRayServletFilter` que cria segmentos para chamadas HTTP de entrada. A amostra inclui um bloco estático na classe `WebConfig` que configura o registrador global com plugins e regras de amostragem. **Example src/main/java/scorekeep/WebConfig.java - gravador** ``` import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter; import com.amazonaws.xray.plugins.ECSPlugin; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; ... @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new ECSPlugin()).withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); ... } } ``` Este exemplo usa o builder para carregar regras de amostragem a partir de um arquivo chamado `sampling-rules.json`. As regras de amostragem determinam a taxa na qual o SDK registra segmentos para as solicitações recebidas. **Example src/main/java/resources/sampling-rules.json** ``` { "version": 1, "rules": [ { "description": "Resource creation.", "service_name": "*", "http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` O arquivo de regras de amostragem define quatro regras de amostragem personalizadas e a regra padrão. Para cada solicitação de entrada, o SDK avalia as regras personalizadas na ordem em que são definidas. O SDK aplica a primeira regra que corresponde ao método, ao caminho e ao nome do serviço da solicitação. Para o Scorekeep, a primeira regra detecta todas as solicitações POST (chamadas de criação de recursos) aplicando um destino fixo de uma solicitação por segundo e uma taxa de 1.0 ou 100% de solicitações após o destino fixo ser alcançado. As outras três regras personalizadas se aplicam a uma taxa fixa de 5%, sem destino fixo para leituras de estado, jogo e sessão (solicitações GET). Isso minimiza o número de rastreamentos das chamadas periódicas que o front-end faz automaticamente a cada poucos segundos para garantir que o conteúdo esteja atualizado. Para todas as outras solicitações, o arquivo define uma taxa padrão de uma solicitação por segundo e uma taxa de 10%. O aplicativo de amostra também mostra como usar recursos avançados, tais como instrumentação de cliente do SDK manual, criação de subsegmentos adicionais e chamadas HTTP de saída. Para obter mais informações, consulte [AWS X-Ray aplicação de amostra](xray-scorekeep.md). ## Opcional: política de menor privilégio Os contêineres do ECS do Scorekeep acessam recursos usando políticas de acesso total, como `AmazonSNSFullAccess` e `AmazonDynamoDBFullAccess`. Usar políticas de acesso total não é a prática recomendada para aplicativos de produção. O exemplo a seguir atualiza a política do IAM do DynamoDB para melhorar a segurança do aplicativo. Para saber mais sobre as melhores práticas de segurança nas políticas do IAM, consulte [Gerenciamento de identidade e acesso para AWS X-Ray](security-iam.md). **Example modelo cf-resources.yaml Definição de função ECSTask** ``` ECSTaskRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Principal: Service: - "ecs-tasks.amazonaws.com" Action: - "sts:AssumeRole" ManagedPolicyArns: - "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess" - "arn:aws:iam::aws:policy/AmazonSNSFullAccess" - "arn:aws:iam::aws:policy/AWSXrayFullAccess" RoleName: "scorekeepRole" ``` Para atualizar sua política, primeiro identifique os ARNs dos recursos do DynamoDB. Em seguida, use o ARN em uma política personalizada do IAM. Por fim, aplique essas políticas ao perfil de instância. **Para identificar o ARN do seu recurso do DynamoDB:** 1. Abra o [console do DynamoDB](https://console.aws.amazon.com/dynamodbv2). 1. Selecione **Tabelas** na barra de navegação à esquerda. 1. Escolha qualquer uma das opções `scorekeep-*` para exibir a página de detalhes da tabela. 1. Na guia **Visão geral**, escolha **Informações adicionais** para expandir a seção e visualizar o nome do recurso da Amazon (ARN). Copie o valor. 1. Insira o ARN na política do IAM a seguir, substituindo os valores `AWS_REGION` e `AWS_ACCOUNT_ID` por sua região específica e ID da conta. Essa nova política permite somente as ações especificadas, em vez da política `AmazonDynamoDBFullAccess`, que permite qualquer ação. **Example** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query" ], "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/scorekeep-*" } ] } ``` ------ As tabelas criadas pelo aplicativo seguem uma convenção de nomenclatura consistente. Você pode usar o formato `scorekeep-*` para indicar todas as tabelas do Scorekeep. **Alterar a política do IAM** 1. Abra o [Perfil da tarefa do Scorekeep (scorekeepRole)](https://console.aws.amazon.com/iamv2/home#/roles/details/scorekeepRole) no console do IAM. 1. Marque a caixa de seleção ao lado da política `AmazonDynamoDBFullAccess` e selecione **Remover** para remover essa política. 1. Escolha **Adicionar permissões**, depois **Anexar políticas** e, finalmente, **Criar política**. 1. Escolha a guia **JSON** e cole a política criada acima. 1. Na parte inferior da página, selecione **Próximo: Tags**. 1. Escolha **Próximo: Revisar** na parte inferior da página. 1. Para **Nome**, atribua um nome para a política. 1. Escolha **Criar política** na parte inferior da página. 1. Anexe a política recém-criada ao perfil `scorekeepRole`. Pode levar alguns minutos para que a política anexada entre em vigor. Se você anexou a nova política à `scorekeepRole` função, deverá desanexá-la antes de excluir a CloudFormation pilha, pois essa política anexada impedirá que a pilha seja excluída. A política pode ser desanexada automaticamente excluindo a política. **Remover sua política do IAM personalizada** 1. Abra o [console do IAM](https://console.aws.amazon.com/iam). 1. Escolha **Políticas** na barra de navegação à esquerda. 1. Pesquise o nome da política personalizada que você criou anteriormente nesta seção e escolha o botão de rádio ao lado do nome da política para destacá-la. 1. Escolha o menu suspenso **Ações** e selecione **Excluir**. 1. Digite o nome da política personalizada e escolha **Excluir** para confirmar a exclusão. Isso separará automaticamente a política do perfil `scorekeepRole`. ## Limpeza Siga estas etapas para excluir os recursos do aplicativo Scorekeep: **nota** Se você criou e anexou políticas personalizadas usando a seção anterior deste tutorial, deverá remover a política do `scorekeepRole` antes de excluir a CloudFormation pilha. ------ #### [ Console de gerenciamento da AWS ] **Exclua o aplicativo de amostra usando o Console de gerenciamento da AWS** 1. Abra o [console do CloudFormation](https://console.aws.amazon.com/cloudformation/). 1. Escolha o botão de opção ao lado do nome da pilha `scorekeep` na lista e selecione **Excluir**. 1. A CloudFormation pilha agora está sendo excluída. O status da pilha permanecerá `DELETE_IN_PROGRESS` por alguns minutos até que todos os recursos sejam excluídos. O status será atualizado periodicamente ou você poderá atualizar a página. ------ #### [ AWS CLI ] **Exclua o aplicativo de amostra usando o AWS CLI** 1. Digite o seguinte AWS CLI comando para excluir a CloudFormation pilha: ``` aws cloudformation delete-stack --stack-name scorekeep ``` 1. Espere até que a CloudFormation pilha não exista mais, o que levará cerca de cinco minutos. Use o AWS CLI comando a seguir para verificar o status: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## Próximas etapas Saiba mais sobre o X-Ray no próximo capítulo, [AWS X-RayConceitos do](xray-concepts.md). Para instrumentar seu próprio aplicativo, saiba mais sobre o X-Ray SDK for Java ou um dos outros X-Ray SDKs: + **X-Ray SDK para Java**: [AWS X-Ray SDK for Java](xray-sdk-java.md) + **X-Ray SDK para Node.js**: [AWS X-Ray SDK para Node.js](xray-sdk-nodejs.md) + **X-Ray SDK para .NET**: [AWS X-Ray SDK para .NET](xray-sdk-dotnet.md) Para executar o daemon X-Ray localmente ou ligado AWS, consulte. [AWS X-Ray daemon](xray-daemon.md) Para contribuir com o aplicativo de amostra em GitHub, consulte [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted). # Instrumentando manualmente os clientes do AWS SDK **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O X-Ray SDK for Java instrumenta automaticamente AWS todos os clientes SDK quando [você inclui AWS o submódulo SDK Instrumentor](xray-sdk-java.md#xray-sdk-java-dependencies) em suas dependências de compilação. Você pode desativar a instrumentação automática do cliente removendo o submódulo Instrumentor. Isso permite que você instrumente alguns clientes manualmente enquanto ignora outros, ou use manipuladores de rastreamento diferentes para clientes diferentes. Para ilustrar o suporte à instrumentação de clientes AWS SDK específicos, o aplicativo passa um manipulador de rastreamento para `AmazonDynamoDBClientBuilder` um manipulador de solicitações no modelo de usuário, jogo e sessão. Essa alteração de código instrui o SDK a instrumentar todas as chamadas para o DynamoDB usando esses clientes. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java)— Instrumentação manual AWS do cliente SDK** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); public class SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client); ``` Se você remover o submódulo AWS SDK Instrumentor das dependências do projeto, somente os clientes AWS SDK instrumentados manualmente aparecerão no mapa de rastreamento. # Criar subsegmentos adicionais **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Na classe de modelo de usuário, o aplicativo cria manualmente subsegmentos para agrupar todas as chamadas de downstream feitas na função `saveUser` e adiciona metadados. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java) – Subsegmentos personalizados** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` # Gravando anotações, metadados e usuário IDs **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Na classe de modelos de jogos, o aplicativo registra objetos `Game` em um bloco de [metadados](xray-sdk-java-segment.md#xray-sdk-java-segment-metadata) toda vez que salva um jogo no DynamoDB. Separadamente, o aplicativo grava o jogo IDs em [anotações](xray-sdk-java-segment.md#xray-sdk-java-segment-annotations) para uso com expressões de [filtro](xray-console-filters.md). **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java): anotações e metadados** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` No controlador de movimentação, o aplicativo registra o [usuário IDs](xray-sdk-java-segment.md#xray-sdk-java-segment-userid) com`setUser`. IDsOs usuários são registrados em um campo separado nos segmentos e são indexados para uso com a pesquisa. **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — ID do usuário** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` # Instrumentar chamadas HTTP de saída **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry A classe de usuário de fábrica mostra como o aplicativo usa a versão `HTTPClientBuilder`do X-Ray SDK para Java para instrumentar chamadas HTTP de saída. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java)— HTTPClient instrumentação** ``` import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://uinames.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` Se você usa atualmente `org.apache.http.impl.client.HttpClientBuilder`, pode simplesmente trocar a declaração de importação dessa classe por uma para `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder`. # Instrumentação de chamadas para um banco de dados PostgreSQL **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O arquivo `application-pgsql.properties` adiciona o interceptor de rastreamento do X-Ray PostgreSQL à fonte de dados criada em [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java). **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties): instrumentação de banco de dados PostgreSQL** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **nota** Consulte [Configuração de bancos de dados com Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.managing.db.html) no *AWS Elastic Beanstalk Guia do desenvolvedor* para detalhes sobre como adicionar um banco de dados PostgreSQL ao ambiente de aplicativos. A página de demonstração do X-Ray na ramificação `xray` inclui uma demonstração que usa a fonte de dados instrumentada para gerar rastreamentos que mostram informações sobre as consultas SQL que ela gera. Navegue até o caminho `/#/xray` no aplicativo em execução ou selecione **Powered by AWS X-Ray(Desenvolvido pelo &xraylong;)** na barra de navegação, para ver a página de demonstração. ![\[AWS X-Ray integration demo page showing game session tracing and SQL query tracing options.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-demo.png) Selecione **Trace SQL queries** para simular sessões de jogos e armazenar os resultados no banco de dados anexado. Em seguida, escolha **Exibir traços no AWS X-Ray** para ver uma lista filtrada dos rastreamentos que atingem a `/api/history` rota da API. Selecione um dos rastreamentos na lista para ver o cronograma, incluindo a consulta SQL. ![\[Timeline view of a trace showing method, response, duration, and age for a GET request.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-trace-sql.png) # Funções de instrumentação AWS Lambda **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O Scorekeep usa duas AWS Lambda funções. A primeira é a função Node.js na ramificação `lambda` que gera nomes aleatórios para novos usuários. Quando um usuário cria uma sessão sem informar um nome, o aplicativo chama uma função denominada `random-name` com o AWS SDK para Java. O X-Ray SDK for Java registra informações sobre a chamada para o Lambda em um subsegmento, como qualquer outra chamada feita com um cliente SDK instrumentado. AWS **nota** A execução da função `random-name` do Lambda requer a criação de recursos adicionais fora do ambiente do Elastic Beanstalk. Consulte o arquivo leia-me para obter mais informações e instruções: [AWS Lambda Integration](https://github.com/awslabs/eb-java-scorekeep/tree/xray/README.md#aws-lambda-integration). A segunda função, `scorekeep-worker`, é uma função Python que pode ser executada independentemente da API do Scorekeep. Quando um jogo termina, a API grava o ID da sessão e o ID do jogo em uma fila do SQS. A função de operador lê itens da fila e chama a API do Scorekeep para criar registros completos de cada sessão do jogo para armazenamento no Amazon S3. O Scorekeep inclui CloudFormation modelos e scripts para criar as duas funções. Como você precisa empacotar o X-Ray SDK com o código da função, os modelos criam as funções sem nenhum código. Quando você implanta o Scorekeep, um arquivo de configuração incluído na pasta `.ebextensions` cria um pacote de origem que inclui o SDK e atualiza o código da função e a configuração com a AWS Command Line Interface. **Topics** + [Nome aleatório](#scorekeep-lambda-randomname) + [Operador](#scorekeep-lambda-worker) ## Nome aleatório O Scorekeep chama a função de nome aleatório quando um usuário inicia uma sessão do jogo sem fazer login ou especificando um nome de usuário. Quando o Lambda processa a chamada a `random-name`, ele lê o [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader), que contém o ID de rastreamento e a decisão de amostragem gravados pelo X-Ray SDK para Java. Para cada solicitação amostrada, o Lambda executa o daemon do X-Ray e grava dois segmentos. O primeiro registra informações sobre a chamada ao Lambda que invoca a função. Esse segmento contém as mesmas informações que o subsegmento registrado pelo Scorekeep, mas do ponto de vista do Lambda. O segundo segmento representa o trabalho que a função faz. O Lambda passa o segmento de função para o X-Ray SDK por meio do contexto da função. Ao instrumentar uma função do Lambda, você não usa o SDK para [criar um segmento para as solicitações de entrada](xray-sdk-nodejs-middleware.md). O Lambda fornece o segmento e você usa o SDK para instrumentar clientes e gravar subsegmentos. ![\[Mapa de rastreamento que mostra como o Scorekeep chama uma função do Lambda a fim de obter nomes aleatórios para novos usuários\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-lambda-node.png) A função `random-name` é implementada em Node.js. Ele usa o SDK do Node.js para JavaScript enviar notificações com o Amazon SNS e o X-Ray SDK para Node.js para AWS instrumentar o cliente do SDK. Para gravar anotações, a função cria um subsegmento personalizado com `AWSXRay.captureFunc` e grava anotações na função instrumentada. No Lambda, não é possível gravar anotações diretamente no segmento da função, apenas em um subsegmento que você criar. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js): função do lambda de nome aleatório** ``` var AWSXRay = require('aws-xray-sdk-core'); var AWS = AWSXRay.captureAWS(require('aws-sdk')); AWS.config.update({region: process.env.AWS_REGION}); var Chance = require('chance'); var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first(); AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); }); // Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } }); }; exports.handler = myFunction; ``` Essa função é criada automaticamente quando você implanta o aplicativo de amostra para o Elastic Beanstalk. A ramificação `xray` inclui um script para criar uma função do Lambda vazia. Os arquivos de configuração na `.ebextensions` pasta criam o pacote de funções `npm install` durante a implantação e, em seguida, atualizam a função Lambda com a CLI AWS . ## Operador A função de operador instrumentada é fornecida em sua própria ramificação `xray-worker`, uma vez que ela não pode executar a menos que você crie a função de operador e os recursos relacionados antes. Consulte o [leia-me da ramificação](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/README.md) para instruções. A função é acionada por um evento agrupado da Amazon CloudWatch Events a cada 5 minutos. Quando ela é executada, a função obtém um item de uma fila do Amazon SQS que o Scorekeep gerencia. Cada mensagem contém informações sobre um jogo concluído. O operador obtém o registro de jogos e documentos de outras tabelas às quais o registro do jogo faz referência. Por exemplo, o registro do jogo no DynamoDB inclui uma lista de movimentos executados durante o jogo. A lista não contém os movimentos em si, mas sim IDs os movimentos armazenados em uma tabela separada. As sessões e os estados também são armazenados como referências. Isso impede que as entradas na tabela de jogos sejam muito grandes, mas requer chamadas adicionais para obter todas as informações sobre o jogo. O operador cancela as referências a todas essas entradas e cria um registro completo do jogo como um único documento no Amazon S3. Quando quiser analisar os dados, você poderá executar consultas diretamente no Amazon S3 com o Amazon Athena sem executar migrações de dados que exigem muita leitura para obter os dados do DynamoDB. ![\[Mapa de rastreamento que mostra como a função de operador do Scorekeep usa o Amazon SQS, o Amazon S3 e a API do Scorekeep.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-lambdaworker-node.png) A função de operador tem o rastreamento ativo em sua configuração no AWS Lambda. Ao contrário da função de nome aleatório, o trabalhador não recebe uma solicitação de um aplicativo instrumentado e, portanto, AWS Lambda não recebe um cabeçalho de rastreamento. Com o rastreamento ativo, o Lambda cria o ID de rastreamento e toma as decisões de amostragem. O X-Ray SDK para Python está apenas algumas linhas na parte superior da função que importa o SDK e executa `patch_all` sua função para corrigir o e que ele usa para AWS SDK para Python (Boto) chamar o Amazon SQS HTTclients e o Amazon S3. Quando o operador chama a API do Scorekeep, o SDK adiciona o [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader) à solicitação para rastrear chamadas por meio da API. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py) -- função do lambda do operador** ``` import os import boto3 import json import requests import time from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all patch_all() queue_url = os.environ['WORKER_QUEUE'] def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3') # Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ... ``` # Instrumentar código de inicialização **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O X-Ray SDK para Java cria segmentos para solicitações de entrada automaticamente. Desde que uma solicitação esteja dentro do escopo, você pode usar clientes instrumentados e gravar subsegmentos sem problema. No entanto, se você tentar usar um cliente instrumentado no código de inicialização, obterá um [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html). O código de inicialização é executado fora do request/response fluxo padrão de um aplicativo web, então você precisa criar segmentos manualmente para instrumentá-lo. O Scorekeep mostra a instrumentação do código de inicialização em seus arquivos `WebConfig`. O Scorekeep chama um banco de dados SQL e o Amazon SNS durante a inicialização. ![\[Diagram showing client requests to Scorekeeper-init, which connects to SQL database and SNS.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-init.png) A classe `WebConfig` padrão cria uma assinatura do Amazon SNS para notificações. Para fornecer um segmento para o X-Ray SDK gravar quando o cliente do Amazon SNS for usado, o Scorekeep chama `beginSegment` e `endSegment` no gravador global. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49)— Cliente AWS SDK instrumentado no código de inicialização** ``` AWSXRay.beginSegment("Scorekeep-init"); if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); } } AWSXRay.endSegment(); ``` Em `RdsWebConfig`, que é usada pelo Scorekeep quando um banco de dados do Amazon RDS está conectado, a configuração também cria um segmento para o cliente SQL que o Hibernate usa ao aplicar o esquema do banco de dados durante a inicialização. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83): cliente de banco de dados SQL instrumentado no código de inicialização** ``` @PostConstruct public void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor); AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment(); } ``` `SchemaExport` é executado automaticamente e usa um cliente SQL. Uma vez que o cliente é instrumentado, o Scorekeep deve substituir a implementação padrão e fornecer um segmento para o SDK usar quando o cliente for invocado. # Scripts de instrumentação **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Você também pode instrumentar código que não faz parte de seu aplicativo. Quando o daemon do X-Ray está em execução, ele retransmite todos os segmentos que recebe para o X-Ray, mesmo que eles não tenham sido gerados pelo X-Ray SDK. O Scorekeep usa seus próprios scripts para instrumentar o build que compila o aplicativo durante a implantação. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh): script de compilação instrumentado** ``` SEGMENT=$(python bin/xray_start.py) gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$? if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1 fi python bin/xray_success.py "$SEGMENT" ``` [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py), [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py) and [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py) são scripts simples do Python que constroem objetos de segmento, convertem-nos em documentos JSON e envia-os para o daemon por meio de UDP. Se a compilação do Gradle falhar, você poderá encontrar a mensagem de erro clicando no nó **scorekeep-build** no mapa de serviço do console do X-Ray. ![\[Diagram showing client connection to Scorekeep-build with average time of 14.6s and 0.07/min.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-builderror.png) ![\[Timeline view showing Scorekeep-build process with 14.6 second duration and warning icon.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-timeline-builderror.png) ![\[Error message showing build failure due to missing ElasticBeanstalkPlugin symbol in RdsWebConfig class.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-exception-builderror.png) # Instrumentar o cliente do aplicativo web **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Na ramificação [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito), o Scorekeep usa o Amazon Cognito para permitir que os usuários criem uma conta e façam login com ela para recuperar informações de um grupo de usuários do Amazon Cognito. Quando um usuário faz login, o Scorekeep usa um pool de identidade do Amazon Cognito para obter credenciais AWS temporárias para uso com o. AWS SDK para JavaScript O grupo de identidades é configurado para permitir que os usuários conectados rastreiem dados para o AWS X-Ray. O aplicativo web usa essas credenciais para gravar o ID do usuário conectado, o caminho do navegador e a visualização de chamadas do cliente para a API do Scorekeep. A maior parte do trabalho é feita em uma classe de serviço chamada `xray`. Essa classe de serviço oferece métodos para gerar os identificadores necessários, criar segmentos em andamento, finalizar segmentos e enviar documentos de segmentos à API do X-Ray. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js): gravar e carregar segmentos** ``` ... service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24); var id = service.getHexId(16); var startTime = service.getEpochTime(); segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } }; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; } service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); } service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) } ``` Esses métodos são chamados no cabeçalho e nas funções `transformResponse` nos serviços do recurso que o aplicativo web usa para chamar a API do Scorekeep. Para incluir o segmento do cliente no mesmo rastreamento que o segmento gerado pela API, a aplicação web deve incluir o ID do rastreamento e o ID do segmento em um [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader) (`X-Amzn-Trace-Id`) que o X-Ray SDK possa ler. Quando a aplicação Java instrumentada recebe uma solicitação com esse cabeçalho, o X-Ray SDK para Java usa o mesmo ID de rastreamento e torna o segmento do cliente da aplicação web o pai do respectivo segmento. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js): gravar segmentos para chamadas de recurso angular e gravar cabeçalhos de rastreamento** ``` var module = angular.module('scorekeep'); module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {}, get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, }, ... ``` O mapa do serviço resultante inclui um nó para o cliente do aplicativo web. ![\[\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-client.png) Os rastreamentos que incluem segmentos do aplicativo web mostram a URL que o usuário vê no navegador (caminhos começando com `/#/`). Sem instrumentação de cliente, você só obtém a URL do recurso da API que o aplicativo web chama (caminhos começando com `/api/`). ![\[\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-traces-client.png) # Usar clientes instrumentais em threads de operador **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O Scorekeep usa um thread de operador para publicar uma notificação para o Amazon SNS quando um usuário ganha um jogo. A publicação da notificação demora mais que o restante das operações de solicitação combinadas, e não afeta o cliente ou o usuário. Portanto, a execução da tarefa de forma assíncrona é uma boa maneira de melhorar o tempo de resposta. No entanto, o X-Ray SDK para Java não sabe qual segmento estava ativo quando o thread foi criado. Como resultado, quando você tenta usar o AWS SDK para Java cliente instrumentado dentro do encadeamento, ele lança um`SegmentNotFoundException`, travando o encadeamento. **Example Web-1.error.log** ``` Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) ... ``` Para corrigir isso, a aplicação usa `GetTraceEntity` para obter uma referência ao segmento no thread principal e `Entity.run()` para passar o segmento de volta para o gravador no thread de operador. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70): passar contexto de rastreamento para um thread de operador** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html); import [com.amazonaws.xray.entities.Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Entity segment = recorder.getTraceEntity(); Thread comm = new Thread() { public void run() { segment.run(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); } } ``` Como a solicitação agora é resolvida antes da chamada para o Amazon SNS, a aplicação cria um subsegmento separado para o thread. Isso evita que o X-Ray SDK feche o segmento antes de registrar a resposta do Amazon SNS. Se nenhum subsegmento estava aberto quando o Scorekeep resolveu a solicitação, a resposta do Amazon SNS poderá ser perdida. ![\[\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-workerthread.png) Consulte [Passar o contexto do segmento entre threads em um aplicativo multithreaded](xray-sdk-java-multithreading.md) para obter mais informações sobre multithreading.