AWS X-Ray SDK para Java

O X-Ray SDK para Java é um conjunto de bibliotecas para aplicações Java que fornece classes e métodos para gerar e enviar dados de rastreamento ao daemon do X-Ray. Os dados de rastreamento incluem informações sobre as solicitações HTTP de entrada atendidas pela aplicação e as chamadas que a aplicação faz para serviços subsequentes usando o SDK da AWS, clientes HTTP ou um conector de banco de dados SQL. Você também pode criar segmentos manualmente e adicionar informações de depuração em anotações e metadados.

O X-Ray SDK para Java é um projeto de código aberto. Você pode acompanhar o projeto, além de enviar problemas e puxar solicitações no GitHub: github.com/aws/aws-xray-sdk-java

Comece adicionando AWSXRayServletFilter como um filtro de servlet para rastrear as solicitações de entrada. Um filtro de servlet cria um segmento. Embora o segmento esteja aberto, você pode usar os métodos do cliente do SDK para adicionar informações ao segmento e criar subsegmentos para rastrear as chamadas subsequentes. O SDK também registra automaticamente exceções que seu aplicativo lança enquanto o segmento está aberto.

A partir da versão 1.3, você pode instrumentar seu aplicativo usando a programação orientada a aspectos (AOP) no Spring. Isso significa que você pode instrumentar a aplicação enquanto ela está sendo executada na AWS sem adicionar nenhum código no runtime da aplicação.

Em seguida, use o X-Ray SDK para Java para instrumentar clientes do AWS SDK for Java incluindo o submódulo Instrumentor do SDK na configuração da compilação. Sempre que você faz uma chamada para um recurso ou AWS service (Serviço da AWS) subsequente com um cliente instrumentado, o SDK registra informações sobre a chamada em um subsegmento. Os Serviços da AWS e os recursos que você acessa dentro dos serviços aparecem como nós subsequentes no mapa de rastreamento para ajudar a identificar erros e problemas de controle de utilização em conexões específicas.

Se você não deseja instrumentar todas as chamadas subsequentes para Serviços da AWS, pode sair do submódulo Instrumentor e escolher quais clientes instrumentar. Instrumente clientes individuais adicionando um TracingHandler a um cliente de serviço de SDK da AWS.

Outros submódulos do X-Ray SDK para Java oferecem instrumentação para as chamadas subsequentes para APIs da web HTTP e bancos de dados SQL. Você pode usar as versões HTTPClient e HTTPClientBuilder do X-Ray SDK para Java no submódulo Apache HTTP para instrumentar clientes do Apache HTTP. Para instrumentar consultas SQL, adicione o interceptor do SDK para sua fonte de dados.

Depois que você começar a usar o SDK, personalize seu comportamento configurando o gravador e o filtro de servlet. Você pode adicionar plug-ins para registrar dados sobre os recursos de computação que executam sua aplicação, personalizar o comportamento de amostragem, estipulando regras de amostragem, e definir o nível de log para ver mais ou menos informações do SDK nos logs da aplicação.

Registre informações adicionais sobre as solicitações e o trabalho que o a aplicação faz em anotações e metadados. Anotações são simples pares de chave-valor que são indexados para serem usados com expressões de filtro para que você possa pesquisar rastreamentos que contêm dados específicos. As entradas de metadados são menos restritivas e podem registrar matrizes e objetos inteiros: tudo o que pode ser serializado em JSON.

Quando você tem uma grande quantidade de clientes instrumentados em seu código, um único segmento de solicitação pode conter muitos subsegmentos, um para cada chamada feita com um cliente instrumentado. Você pode organizar e agrupar subsegmentos integrando chamadas de clientes em subsegmentos personalizados. Você pode criar um subsegmento personalizado para uma função inteira ou qualquer seção de código e registrar metadados e anotações no subsegmento em vez de gravar tudo no segmento principal.

Submódulos

Você pode baixar o X-Ray SDK para Java do Maven. O X-Ray SDK para Java é dividido em submódulos por caso de uso, com uma lista de materiais para gerenciamento de versões:

Se você usar o Maven ou o Gradle para criar sua aplicação, adicione o X-Ray SDK para Java à configuração de compilação.

Para documentação de referência das classes e métodos do SDK, consulte Referência de API do AWS X-Ray SDK para Java.

Requisitos

O X-Ray SDK para Java requer o Java 8 ou posterior, a API Servlet 3, o SDK da AWS e Jackson.

O SDK depende das seguintes bibliotecas para compilação e tempo de execução:

Essas dependências são declaradas no arquivo pom.xml do SDK e serão incluídas automaticamente se você criar usando Maven ou Gradle.

Se você usar uma biblioteca que esteja incluída no X-Ray SDK para Java, deverá usar a versão incluída. Por exemplo, se você já usa Jackson em tempo de execução e inclui arquivos JAR em sua implantação para essa dependência, deverá remover esses arquivos JAR porque o SDK JAR inclui suas próprias versões de bibliotecas Jackson.

Gerenciar dependências

O SDK para Java do X-Ray para Java está disponível no Maven:

Se você usar o Maven para criar seu aplicativo, adicione o SDK como uma dependência no arquivo pom.xml.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
  </dependency>
</dependencies>

Para Gradle, adicione o SDK como uma dependência de tempo de compilação ao arquivo build.gradle.

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")
  compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
  testCompile("junit:junit:4.11")
}
dependencyManagement {
    imports {
        mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
        mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    }
}

Se você usar o Elastic Beanstalk para implantar a aplicação, poderá usar o Maven ou o Gradle para criar na instância toda vez que implantar, em vez de criar e carregar um grande arquivo que inclui todas as suas dependências. Consulte o aplicativo de amostra para obter um exemplo que usa Gradle.

Métricas do AWS X-Ray do X-Ray SDK para Java

Este tópico descreve o namespace, as métricas e as dimensões do AWS X-Ray. Você pode usar o X-Ray SDK para Java para publicar métricas sem amostragem do Amazon CloudWatch usando os segmentos do X-Ray coletados. Essas métricas são derivadas da hora de início e término do segmento e dos sinalizadores de status de erro, falha e limitação. Use essas métricas de rastreamento para expor novas tentativas e problemas de dependência dentro de subsegmentos.

O CloudWatch é um repositório de métricas. Uma métrica é um conceito fundamental no CloudWatch e representa um conjunto de pontos de dados ordenados por tempo. Você (ou os Serviços da AWS) publica pontos de dados de métricas no CloudWatch e recupera estatísticas sobre os pontos de dados como uma série ordenada de dados de séries temporais.

As métricas são definidas exclusivamente por um nome, um namespace e uma ou mais dimensões. Cada ponto de dados tem um timestamp e, opcionalmente, uma unidade de medida. Quando você solicita estatísticas, o fluxo de dados apresentado é identificado pelo namespace, pelo nome da métrica e pela dimensão.

Para obter mais informações sobre o CloudWatch, consulte o Guia do usuário do Amazon CloudWatch.

Métricas do CloudWatch para o X-Ray

O namespace ServiceMetrics/SDK inclui as métricas a seguir.

Dimensões do CloudWatch para o X-Ray

Use as dimensões na tabela a seguir para refinar as métricas retornadas para aplicações Java instrumentadas do X-Ray.

Habilitar métricas do CloudWatch para o X-Ray

Use o procedimento a seguir para habilitar métricas de rastreamento na aplicação Java instrumentada.