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á. # Configurar o X-Ray SDK para Java **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 tem 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 HTTP de entrada. **Topics** + [Plug-ins de serviço](#xray-sdk-java-configuration-plugins) + [Regras de amostragem](#xray-sdk-java-configuration-sampling) + [Registro em log](#xray-sdk-java-configuration-logging) + [Listeners de segmento](#xray-sdk-java-configuration-listeners) + [Variáveis de ambiente](#xray-sdk-java-configuration-envvars) + [Propriedades do sistema](#xray-sdk-java-configuration-sysprops) ## Plug-ins de serviço Use `plugins` para registrar informações sobre o serviço que hospeda o aplicativo. **Plugins** + 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: o `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 do Amazon EC2 e do Elastic Beanstalk.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) Para usar um plugin, acione o `withPlugin` em seu `AWSXRayRecorderBuilder`. **Example src/main/java/scorekeep/WebConfig.java - gravador** ``` 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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @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 campo `origin` 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 O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão 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](xray-console-sampling.md) para personalizar a quantidade de dados registrados para cada uma dos aplicativos. O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra. **nota** Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverterá para uma regra local padrão da primeira solicitação a cada segundo e 5% de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar a amostragem APIs ou não conseguir se conectar ao daemon X-Ray, que atua como um proxy TCP para chamadas de API feitas pelo SDK. Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais. **Example 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. **Example src/main/java/myapp/WebConfig.java - configuração do gravador** ``` 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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); 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); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @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. **Example src/com/myapp/web/Startup.java** ``` 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.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); 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) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` Para usar somente regras locais, substitua o `CentralizedSamplingStrategy` por uma `LocalizedSamplingStrategy`. ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## Registro em log Por padrão, o SDK envia mensagens de nível de `ERROR` da aplicação para os logs da aplicação. Você pode habilitar o registro em log em nível de depuração no SDK para gerar logs mais detalhados no arquivo de log da aplicação. Os níveis de log válidos são `DEBUG`, `INFO`, `WARN`, `ERROR` e `FATAL`. O nível de log `FATAL` silencia todas as mensagens de log porque o SDK não registra em log no nível fatal. **Example 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](xray-sdk-java-subsegments.md). ### Injeção de ID de rastreamentos em logs Para expor o ID de rastreamento totalmente qualificado atual às instruções de log, é possível 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 do MDC. Isso expõe o ID de rastreamento à biblioteca de log em uso. Quando um subsegmento termina, seu ID pai é injetado no MDC. **Example 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: + SLF4API de front-end J com back-end Logback + SLF4API de front-end J com back-end Log4J2 + API front-end Log4J2 com backend 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. ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. Inclua o método `withSegmentListener` ao construir o `AWSXRayRecorder`. Isso adiciona uma `SegmentListener` classe, que injeta automaticamente um novo traço IDs no SLF4 J MDC. 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. **Example 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. ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. Inclua o método `withSegmentListener` ao construir o `AWSXRayRecorder`. Isso adicionará uma `SegmentListener` classe, que injeta automaticamente um novo rastreamento totalmente qualificado IDs no SLF4 J MDC. 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. **Example 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. Isto pode ser feito programaticamente ou através de um arquivo de configuração XML. Para saber mais, consulte [Configuração de Logback](http://logback.qos.ch/manual/configuration.html). 1. Insira `%X{AWS-XRAY-TRACE-ID}` em qualquer lugar no `patternLayout` para inserir o ID de rastreamento em instruções de log futuras. O `%X{}` indica que você está recuperando um valor com a chave fornecida do MDC. Para saber mais sobre o PatternLayouts Logback, consulte [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout). ------ #### [ Log4J2 backend ] 1. Localize onde o `patternLayout` está configurado. Isto pode ser feito programaticamente ou através de um arquivo de configuração escrito no formato XML, JSON, YAML ou de propriedades. Para saber mais sobre como configurar o Log4J2 por meio de um arquivo de configuração, consulte [Configuração](https://logging.apache.org/log4j/2.x/manual/configuration.html). Para saber mais sobre como configurar o Log4J2 programaticamente, consulte [Configuração programática](https://logging.apache.org/log4j/2.x/manual/customconfig.html). 1. Insira `%X{AWS-XRAY-TRACE-ID}` em qualquer lugar no `PatternLayout` para inserir o ID de rastreamento em instruções de log futuras. O `%X{}` indica que você está recuperando um valor com a chave fornecida do MDC. [Para saber mais sobre o PatternLayouts Log4J2, consulte Pattern Layout.](https://logging.apache.org/log4j/2.x/manual/layouts.html#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`). **Example `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. **Example 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 receptores de segmento são uma interface para interceptar eventos de ciclo de vida, como o início e o fim de segmentos produzidos pelo `AWSXRayRecorder`. A implementação de uma função de evento do receptor de segmento pode consistir em adicionar a mesma anotação a todos os subsegmentos quando eles são criados com [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-), registrar em log uma mensagem após cada segmento ser enviado para o daemon usando [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) ou registrar consultas enviadas pelos interceptores SQL usando [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) para verificar se o subsegmento representa uma consulta SQL, adicionando outros metadados em caso afirmativo. Para ver a lista completa de funções `SegmentListener`, acesse a documentação do [AWS X-Ray X-Ray Recorder SDK para Java API](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html). O exemplo a seguir mostra como adicionar uma anotação consistente a todos os subsegmentos na criação com [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) e imprimir uma mensagem de log no final de cada segmento com [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-). **Example 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`. **Example 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 é compatível com as variáveis a seguir. + `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, o SDK usa `127.0.0.1:2000` para dados de rastreamento (UDP) e para amostragem (TCP). Use essa variável se você tiver configurado o daemon para [escutar em uma porta diferente](xray-daemon-configuration.md) 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 do grupo de logs associado ao 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 os grupos de logs, consulte [Trabalhar com grupos de logs e fluxos](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). + `AWS_XRAY_TRACING_NAME`: defina um nome de serviço para o SDK usar para segmentos. Sobrepõe o nome do serviço que você definiu na [estratégia de nomeação de segmentos](xray-sdk-java-filters.md#xray-sdk-java-filters-naming) do filtro do servlet. As variáveis de ambiente substituem as [propriedades do sistema](#xray-sdk-java-configuration-sysprops) equivalentes e os valores definidos no código. ## Propriedades do sistema É possível usar propriedades do sistema como uma alternativa específica de JVM a [variáveis de ambiente](#xray-sdk-java-configuration-envvars). O SDK é compatível com as propriedades a seguir. + `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.