Conceitos básicos da aplicação Scorekeep de exemplo

Este tutorial usa a ramificação xray-gettingstarted da aplicação Scorekeep de exemplo, que utiliza o AWS CloudFormation para criar e configurar os recursos que executam a aplicação de exemplo e o daemon do X-Ray no Amazon ECS. A aplicação usa o Spring Framework para implementar uma API da web em JSON e o AWS SDK for Java para conservar os dados no Amazon DynamoDB. Um filtro de servlet na aplicação instrumenta todas as solicitações de entrada atendidas pela aplicação, e um manipulador de solicitações no cliente do SDK da AWS instrumenta chamadas subsequentes para o DynamoDB.

Você pode seguir este tutorial usando o AWS Management Console ou a AWS CLI.

Pré-requisitos

Este tutorial usa o AWS CloudFormation para criar e configurar os recursos que executam a aplicação de exemplo e o daemon do X-Ray. Para instalar e executar o tutorial, você deve cumprir os seguintes pré-requisitos:

Instalar a aplicação Scorekeep usando o 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:

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 serviço e os rastreamentos gerados pela aplicação de exemplo no console do X-Ray e do CloudWatch.

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 a aplicação é inicializada, ele tenta criar uma assinatura para um endereço de e-mail definido em um parâmetro da pilha do CloudFormation. 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 a aplicação com o modelo do CloudFormation, as tabelas do DynamoDB, o cluster do Amazon ECS e outros serviços necessários para executar o Scorekeep no ECS são criados. Um arquivo de definição de tarefas para o ECS é criado por meio do 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.

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 for Java. Para instrumentar essas chamadas, a aplicação simplesmente adota os submódulos relacionados ao SDK da AWS como dependências, e o X-Ray SDK para Java automaticamente instrumenta todos os clientes do SDK da 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.

docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build

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.

...
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")
    }
}

O núcleo, o AWS SDK e os submódulos Instrumentor do AWS SDK são tudo o que é exigido para instrumentar automaticamente quaisquer chamadas downstream feitas com o AWS SDK.

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.

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

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.

{
  "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 ter mais informações, consulte Aplicação de exemplo do AWS X-Ray.

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 práticas recomendadas de segurança em políticas do IAM, consulte Identity and access management for AWS X-Ray.

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.

Se você anexou a nova política ao perfil scorekeepRole, deverá desanexá-la antes de excluir a pilha do CloudFormation, pois essa política anexada impedirá que a pilha seja excluída. A política pode ser desanexada automaticamente excluindo a política.

Limpeza

Siga estas etapas para excluir os recursos da aplicação Scorekeep:

Próximas etapas

Saiba mais sobre o X-Ray no próximo capítulo, Conceitos do AWS X-Ray.

Para instrumentar sua aplicação, saiba mais sobre o X-Ray SDK para Java ou um dos outros X-Ray SDKs:

Para executar o daemon do X-Ray localmente ou na AWS, consulte Daemon do AWS X-Ray.

Para contribuir com o aplicativo de amostra no GitHub, consulte eb-java-scorekeep.