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á.
Conceitos básicos da aplicação Scorekeep de exemplo
nota
End-of-support aviso — Em 25 de fevereiro de 2027, o AWS X-Ray interromperá o suporte para AWS X-Ray SDKs o daemon. Depois de 25 de fevereiro de 2027, você não receberá mais atualizações ou lançamentos. Para obter mais informações sobre o cronograma de suporte, consulteCronograma de fim do suporte do X-Ray SDK e do daemon. 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. OpenTelemetry
Este tutorial usa a xray-gettingstarted ramificação do aplicativo de amostra Scorekeep, usada AWS 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 AWS Management Console ou AWS CLI o.
Seções
Pré-requisitos
Este tutorial é usado AWS 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:
-
Se você usa um usuário do IAM com permissões limitadas, adicione as seguintes políticas de usuário no console do IAM
: -
AWSCloudFormationFullAccess— para acessar e usar CloudFormation -
AmazonS3FullAccess— para fazer upload de um arquivo de modelo para CloudFormation usar o AWS Management Console -
IAMFullAccess— para criar as funções de EC2 instância do Amazon ECS e da Amazon -
AmazonEC2FullAccess— para criar os EC2 recursos da Amazon -
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
-
-
Para executar o tutorial usando o AWS CLI, instale a CLI versão 2.7.9 ou posterior e configure a CLI com o 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
--regiona cada comando da CLI.AWS-REGION -
O Git
deve estar instalado para clonar o repositório da aplicação de exemplo. -
Use o exemplo de código a seguir para clonar a
xray-gettingstartedramificaçã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
Gerar dados de rastreamento
O aplicativo de amostra inclui um aplicativo Web front-end. Use a aplicação web para gerar tráfego para a API e enviar dados de rastreamento para o X-Ray. Primeiro, recupere o URL da aplicação web usando o AWS Management Console ou a AWS CLI:
Usar a aplicação web para gerar dados de rastreamento
-
Escolha Create para criar um usuário e uma sessão.
-
Digite um game name, defina as Rules para Tic Tac Toe e, em seguida, escolha Create para criar um jogo.
-
Escolha Play para iniciar o jogo.
-
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 AWS Management Console
Você pode ver o mapa de rastreamento e os traços gerados pelo aplicativo de amostra no X-Ray e nos CloudWatch consoles.
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.
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 aplicação 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.
exemplo src/main/java/scorekeep/WebConfig.java - filtro de servlet
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
...
@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 aplicação 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 aplicação 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.
exemplo 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 buildexemplo 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.
exemplo 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, a aplicação executa o daemon do X-Ray em um contêiner que é implantado com o aplicação Scorekeep no ECS como um contêiner auxiliar. Confira o tópico Daemon do X-Ray para obter mais informações.
exemplo 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.
exemplo 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.
exemplo 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.
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 aplicações de produção. O exemplo a seguir atualiza a política do IAM do DynamoDB para melhorar a segurança da aplicação. 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.
exemplo 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:
-
Abra o console do DynamoDB
. -
Selecione Tabelas na barra de navegação à esquerda.
-
Escolha qualquer uma das opções
scorekeep-*para exibir a página de detalhes da tabela. -
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.
-
Insira o ARN na política do IAM a seguir, substituindo os valores
AWS_REGIONeAWS_ACCOUNT_IDpor sua região específica e ID da conta. Essa nova política permite somente as ações especificadas, em vez da políticaAmazonDynamoDBFullAccess, que permite qualquer ação.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
-
Abra o Perfil da tarefa do Scorekeep (scorekeepRole)
no console do IAM. -
Marque a caixa de seleção ao lado da política
AmazonDynamoDBFullAccesse selecione Remover para remover essa política. -
Escolha Adicionar permissões, depois Anexar políticas e, finalmente, Criar política.
-
Escolha a guia JSON e cole a política criada acima.
-
Na parte inferior da página, selecione Próximo: Tags.
-
Escolha Próximo: Revisar na parte inferior da página.
-
Para Nome, atribua um nome para a política.
-
Escolha Criar política na parte inferior da página.
-
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
-
Abra o console do IAM
. -
Escolha Políticas na barra de navegação à esquerda.
-
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.
-
Escolha o menu suspenso Ações e selecione Excluir.
-
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 da aplicação 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.
Próximas etapas
Saiba mais sobre o X-Ray no próximo capítulo, AWS X-Ray conceitos.
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
-
X-Ray SDK para Node.js: AWS X-Ray SDK para Node.js
-
X-Ray SDK para .NET: AWS X-Ray SDK para .NET
Para executar o daemon X-Ray localmente ou ligado AWS, consulte. AWS X-Ray daemon
Para contribuir com o aplicativo de amostra em GitHub, consulte eb-java-scorekeep
