Configurando o X-Ray SDK para Java - AWS X-Ray
Plug-ins de serviçoRegras de amostragemRegistro em logListeners de segmentoVariáveis de ambientePropriedades do sistema

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

Configurando o X-Ray SDK para Java

O X-Ray SDK for Java inclui uma classe chamada AWSXRay que fornece o gravador global. Este é um TracingHandler que pode ser usado para instrumentar o código. Você pode configurar o gravador global para personalizar o AWSXRayServletFilter que cria segmentos para chamadas recebidasHTTP.

Plug-ins de serviço

Use plugins para registrar informações sobre o serviço que hospeda a aplicação.

Plug-ins

  • Amazon EC2 — EC2Plugin adiciona o ID da instância, a zona de disponibilidade e o grupo de CloudWatch registros.

  • Elastic Beanstalk: o ElasticBeanstalkPlugin adiciona o nome do ambiente, o rótulo da versão e o ID de implantação.

  • Amazon ECS — ECSPlugin adiciona o ID do contêiner.

  • Amazon EKS — EKSPlugin adiciona o ID do contêiner, o nome do cluster, o ID do pod e o grupo de CloudWatch registros.

Segmente dados de recursos com os plug-ins Amazon EC2 e Elastic Beanstalk.

Para usar um plugin, acione o withPlugin em seu AWSXRayRecorderBuilder.

exemplo src/main/java/scorekeep/ .java WebConfig - gravador
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

O SDK também usa as configurações do plug-in para definir o origin campo no segmento. Isso indica o tipo de AWS recurso que executa seu aplicativo. Quando você usa vários plug-ins, o SDK usa a seguinte ordem de resolução para determinar a origem: ElasticBeanstalk > EKS > ECS >EC2.

Regras de amostragem

SDKEle usa as regras de amostragem que você define no console X-Ray para determinar quais solicitações devem ser registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. Crie regras adicionais no console do X-Ray para personalizar a quantidade de dados registrados para cada uma das aplicações.

SDKAplica as regras personalizadas na ordem em que são definidas. Se uma solicitação corresponder a várias regras personalizadas, SDK aplica-se somente a primeira regra.

nota

Se não SDK conseguir acessar o X-Ray para obter as regras de amostragem, ele reverte para uma regra local padrão da primeira solicitação a cada segundo e cinco por cento de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para amostragem APIs de chamadas ou não conseguir se conectar ao daemon X-Ray, que atua como um TCP proxy para API chamadas feitas pelo. SDK

Você também pode configurar o SDK para carregar regras de amostragem de um JSON documento. Eles SDK podem usar regras locais como backup para casos em que a amostragem de X-Ray não está disponível ou usar regras locais exclusivamente.

exemplo sampling-rules.json
{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em /api/move/. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais.

A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados.

Ativado AWS Lambda, você não pode modificar a taxa de amostragem. Se sua função for chamada por um serviço instrumentado, as chamadas que geraram solicitações que foram amostradas por esse serviço serão registradas pelo Lambda. Se o rastreamento ativo estiver habilitado e nenhum cabeçalho de rastreamento estiver presente, o Lambda tomará a decisão de amostragem.

Para fornecer regras de backup em Spring, configure o gravador global com uma CentralizedSamplingStrategy em uma classe de configuração.

exemplo src/main/java/myapp/ .java WebConfig - configuração do gravador
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
  builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

Para Tomcat, adicione um listener que estenda ServletContextListener e registre o listener na descrição da implantação.

exemplo src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Startup.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}
exemplo WEB- INF /web.xml
...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

Para usar somente regras locais, substitua o CentralizedSamplingStrategy por uma LocalizedSamplingStrategy.

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

Registro em log

Por padrão, ele envia mensagens em ERROR nível de SDK saída para os registros do seu aplicativo. Você pode ativar o registro em nível de depuração no SDK para gerar registros mais detalhados no arquivo de log do seu aplicativo. Os níveis de log válidos são DEBUG INFOWARN,ERROR,, FATAL e. FATALo nível de log silencia todas as mensagens de log porque SDK não é registrado no nível fatal.

exemplo application.properties

Defina o nível de registro com a propriedade logging.level.com.amazonaws.xray.

logging.level.com.amazonaws.xray = DEBUG

Use logs de depuração para identificar problemas como subsegmentos não fechados ao gerar subsegmentos manualmente.

Injeção de ID de rastreamentos em logs

Para expor o ID de rastreamento atual totalmente qualificado às suas instruções de log, você pode injetar o ID no contexto de diagnóstico mapeado (). MDC Usando a interface SegmentListener, os métodos são chamados do gravador do X-Ray durante eventos do ciclo de vida do segmento. Quando um segmento ou subsegmento começa, o ID de rastreamento qualificado é injetado no MDC com a chave. AWS-XRAY-TRACE-ID Quando esse segmento termina, a chave é removida doMDC. Isso expõe o ID de rastreamento à biblioteca de log em uso. Quando um subsegmento termina, seu ID pai é injetado no. MDC

exemplo ID de rastreamento totalmente qualificado

O ID totalmente qualificado é representado como TraceID@EntityID

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Esse recurso funciona com aplicativos Java instrumentados com o AWS X-Ray SDK for Java e oferece suporte às seguintes configurações de registro:

  • SLF4Jfront-end com back-end API Logback

  • SLF4Jfront-end com backend API Log4J2

  • Front-end Log4J2 com backend API Log4J2

Consulte as guias a seguir para obter as necessidades de cada front-end e de cada backend.

SLF4J Frontend

  1. Adicione a seguinte dependência Maven ao seu projeto.

    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-slf4j</artifactId>
    <version>2.11.0</version>
</dependency>

  2. Inclua o método withSegmentListener ao construir o AWSXRayRecorder. Isso adiciona uma SegmentListener classe, que injeta automaticamente um novo traço IDs no SLF4JMDC.

    O SegmentListener usa uma string opcional como um parâmetro para configurar o prefixo da instrução de log. O prefixo pode ser configurado das seguintes maneiras:

    • Nenhum: usa o prefixo AWS-XRAY-TRACE-ID padrão.

    • Vazio: usa uma string vazia (por exemplo, "").

    • Personalizado: usa um prefixo personalizado conforme definido na string.

    exemplo Instrução AWSXRayRecorderBuilder
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
Log4J2 front end

  1. Adicione a seguinte dependência Maven ao seu projeto.

    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-log4j</artifactId>
    <version>2.11.0</version>
</dependency>

  2. Inclua o método withSegmentListener ao construir o AWSXRayRecorder. Isso adicionará uma SegmentListener classe, que injeta automaticamente um novo rastreamento totalmente qualificado IDs no SLF4JMDC.

    O SegmentListener usa uma string opcional como um parâmetro para configurar o prefixo da instrução de log. O prefixo pode ser configurado das seguintes maneiras:

    • Nenhum: usa o prefixo AWS-XRAY-TRACE-ID padrão.

    • Vazio: usa uma string vazia (por exemplo, "") e remove o prefixo.

    • Personalizado: usa o prefixo personalizado definido na string.

    exemplo Instrução AWSXRayRecorderBuilder
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
Logback backend

Para inserir o ID de rastreamento em seus eventos de log, você deve modificar o PatternLayout do registrador de logs, que formata cada instrução de log.

  1. Localize onde o patternLayout está configurado. Você pode fazer isso programaticamente ou por meio de um arquivo de XML configuração. Para saber mais, consulte Configuração de Logback.

  2. Insira em %X{AWS-XRAY-TRACE-ID} qualquer lugar do patternLayout para inserir o ID de rastreamento em futuras instruções de registro. %X{}indica que você está recuperando um valor com a chave fornecida pelo. MDC Para saber mais sobre o PatternLayouts Logback, consulte PatternLayout.

Log4J2 backend

  1. Localize onde o patternLayout está configurado. Você pode fazer isso programaticamente ou por meio de um arquivo de configuração escrito no formatoXML, JSONYAML, ou de propriedades.

    Para saber mais sobre como configurar o Log4J2 por meio de um arquivo de configuração, consulte Configuração.

    Para saber mais sobre como configurar o Log4J2 programaticamente, consulte Configuração programática.

  2. Insira em %X{AWS-XRAY-TRACE-ID} qualquer lugar do PatternLayout para inserir o ID de rastreamento em futuras instruções de registro. %X{}indica que você está recuperando um valor com a chave fornecida pelo. MDC Para saber mais sobre o PatternLayouts Log4J2, consulte Pattern Layout.
Exemplo de injeção de ID de rastreamento

A seguir, é mostrado uma string PatternLayout modificada para incluir o ID de rastreamento. O ID de rastreamento é impresso após o nome do thread (%t) e antes do nível de log (%-5p).

exemplo PatternLayout com injeção de ID
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray imprime automaticamente a chave e o ID de rastreamento na instrução de log para facilitar a análise. A seguir é mostrada uma instrução de log usando o PatternLayout modificado.

exemplo Instrução de log com injeção de ID
2019-09-10 18:58:30.844 [nio-5000-exec-4]  AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

A mensagem de log em si é alojada no %m padrão e definida ao chamar o registrador de log.

Listeners de segmento

Os ouvintes de segmentos são uma interface para interceptar eventos do ciclo de vida, como o início e o fim dos segmentos produzidos pelo. AWSXRayRecorder A implementação de uma função de evento de ouvinte de segmento pode ser adicionar a mesma anotação a todos os subsegmentos quando eles são criados com onBeginSubsegment, registrar uma mensagem após cada segmento ser enviado ao daemon usando ou registrar consultas enviadas pelos SQL interceptores usando beforeEndSubsegmentpara verificar se o subsegmento representa uma consulta afterEndSegment, adicionando metadados adicionais em caso afirmativo. SQL

Para ver a lista completa de SegmentListener funções, acesse a documentação do AWS X-Ray Recorder SDK for Java API.

O exemplo a seguir mostra como adicionar uma anotação consistente a todos os subsegmentos na criação com onBeginSubsegment e imprimir uma mensagem de log no final de cada segmento com afterEndSegment.

exemplo MySegmentListener.java
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;

public class MySegmentListener implements SegmentListener {
    .....
    
    @Override
    public void onBeginSubsegment(Subsegment subsegment) {
        subsegment.putAnnotation("annotationKey", "annotationValue");
    }
    
    @Override
    public void afterEndSegment(Segment segment) {
        // Be mindful not to mutate the segment
        logger.info("Segment with ID " + segment.getId());
    }
}

Esse listener de segmento personalizado é então referenciado ao criar o AWSXRayRecorder.

exemplo AWSXRayRecorderBuilder declaração
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

Variáveis de ambiente

Você pode usar variáveis de ambiente para configurar o X-Ray SDK para Java. O SDK suporta as seguintes variáveis.

  • AWS_XRAY_CONTEXT_MISSING: defina como RUNTIME_ERROR para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto.

    Valores válidos

    • RUNTIME_ERROR: lance uma exceção de tempo de execução.

    • LOG_ERROR: registre um erro e continue (padrão).

    • IGNORE_ERROR: ignore o erro e continue.

    Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread.

  • AWS_XRAY_DAEMON_ADDRESS: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, os SDK usos tanto 127.0.0.1:2000 para dados de rastreamento (UDP) quanto para amostragem (TCP). Use essa variável se você tiver configurado o daemon para escutar em uma porta diferente ou se ele estiver sendo executado em um host diferente.

    Formato

    • Mesma porta: address:port

    • Portas diferentes: tcp:address:port udp:address:port

  • AWS_LOG_GROUP— Defina o nome de um grupo de registros para o grupo de registros associado ao seu aplicativo. Se o seu grupo de registros usar a mesma AWS conta e região do seu aplicativo, o X-Ray pesquisará automaticamente os dados de segmento do seu aplicativo usando esse grupo de registros especificado. Para obter mais informações sobre grupos de registros, consulte Trabalhando com grupos e fluxos de registros.

  • AWS_XRAY_TRACING_NAME— Defina um nome de serviço que ele SDK use para segmentos. Sobrepõe o nome do serviço que você definiu na estratégia de nomeação de segmentos do filtro do servlet.

As variáveis de ambiente substituem as propriedades do sistema equivalentes e os valores definidos no código.

Propriedades do sistema

Você pode usar as propriedades do sistema como uma alternativa JVM específica às variáveis de ambiente. O SDK suporta as seguintes propriedades:

  • com.amazonaws.xray.strategy.tracingName: equivalente ao AWS_XRAY_TRACING_NAME.

  • com.amazonaws.xray.emitters.daemonAddress: equivalente ao AWS_XRAY_DAEMON_ADDRESS.

  • com.amazonaws.xray.strategy.contextMissingStrategy: equivalente ao AWS_XRAY_CONTEXT_MISSING.

Caso uma propriedade do sistema e a variável de ambiente equivalente sejam definidas, são usados os valores da variável de ambiente. Ambos os métodos substituem valores definidos no código.