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á.
# AWS X-Ray agente de instrumentação automática 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 agente de AWS X-Ray instrumentação automática para Java é uma solução de rastreamento que instrumenta seus aplicativos web Java com o mínimo esforço de desenvolvimento. O agente permite o rastreamento de aplicativos baseadas em servlets e de todas as solicitações subsequentes do agente feitas com frameworks e bibliotecas compatíveis. Isso inclui solicitações HTTP subsequentes do Apache, solicitações de SDK da AWS e consultas SQL feitas usando um driver JDBC. O agente propaga o contexto do X-Ray, incluindo todos os segmentos e subsegmentos ativos, em todos os threads. A versatilidade e todas as configurações do X-Ray SDK ainda estão disponíveis com o agente do Java. Os padrões adequados foram escolhidos para garantir que o agente trabalhe com o mínimo esforço.
A solução de agente do X-Ray é mais adequada para servidores de aplicativos web Java baseadas em servlets e de solicitação e resposta. Se seu aplicativo usa um framework assíncrono ou não está bem modelada como um serviço de solicitação e resposta, é aconselhável considerar a instrumentação manual com o SDK.
O agente X-Ray é construído usando o kit de ferramentas Distributed Systems Comprehension, ou Di. SCo Di SCo é uma estrutura de código aberto para criar agentes Java que podem ser usados em sistemas distribuídos. Embora não seja necessário entender o Di SCo para usar o agente X-Ray, você pode aprender mais sobre o projeto visitando sua [página inicial em GitHub](https://github.com/awslabs/disco). O agente do X-Ray também é totalmente de código aberto. Para ver o código-fonte, fazer contribuições ou levantar questões sobre o agente, visite seu [repositório em GitHub](https://github.com/aws/aws-xray-java-agent).
## Aplicação de exemplo
A aplicação [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)da amostra é adaptada para ser instrumentada com o agente X-Ray. Essa ramificação não contém filtro de servlet ou configuração de gravador, pois essas funções são executadas pelo agente. Para executar o aplicativo localmente ou usando recursos da AWS , siga as etapas no arquivo readme do aplicativo de exemplo. As instruções sobre como usar o aplicativo de exemplo para gerar rastreamentos do X-Ray estão no [tutorial do aplicativo de exemplo](xray-scorekeep.md).
## Introdução
Para começar a usar o agente do Java de instrumentação automática do X-Ray em seu aplicativo, siga as etapas abaixo.
1. Execute o daemon do X-Ray no seu ambiente. Para obter mais informações, consulte [AWS X-Ray daemon](xray-daemon.md).
1. Baixe a [distribuição mais recente do agente](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip). Descompacte o arquivo e anote a respectiva localização no sistema de arquivos. O conteúdo deve ser semelhante ao apresentado abaixo.
```
disco
├── disco-java-agent.jar
└── disco-plugins
├── aws-xray-agent-plugin.jar
├── disco-java-agent-aws-plugin.jar
├── disco-java-agent-sql-plugin.jar
└── disco-java-agent-web-plugin.jar
```
1. Modifique os argumentos da JVM do aplicativo para incluir o que vem a seguir, que habilita o agente. O argumento `-javaagent` deve ser colocado *antes* do argumento `-jar`, se aplicável. O processo para modificar os argumentos da JVM varia de acordo com as ferramentas e os frameworks que você usa para iniciar o servidor Java. Consulte a documentação do framework do servidor para obter orientação específica.
```
-javaagent://disco-java-agent.jar=pluginPath=//disco-plugins
```
1. Para especificar como o nome do aplicativo aparece no console do X-Ray, defina a variável de ambiente `AWS_XRAY_TRACING_NAME` ou a propriedade do sistema `com.amazonaws.xray.strategy.tracingName`. Se nenhum nome for fornecido, será usado um nome padrão.
1. Reinicie o servidor ou contêiner. As solicitações recebidas e as chamadas subsequentes agora são rastreadas. Se você não vir os resultados esperados, consulte [Solução de problemas](#XRayAutoInstrumentationAgent-Troubleshooting).
## Configuração
O agente do X-Ray é configurado por um arquivo JSON externo fornecido pelo usuário. Por padrão, esse arquivo está na raiz do caminho de classe do usuário (por exemplo, no diretório `resources`) chamado `xray-agent.json`. Você pode configurar um local personalizado para o arquivo de configuração definindo a propriedade do sistema `com.amazonaws.xray.configFile` como o caminho absoluto do sistema de arquivos do arquivo de configuração.
Um exemplo de arquivo de configuração é mostrado a seguir.
```
{
"serviceName": "XRayInstrumentedService",
"contextMissingStrategy": "LOG_ERROR",
"daemonAddress": "127.0.0.1:2000",
"tracingEnabled": true,
"samplingStrategy": "CENTRAL",
"traceIdInjectionPrefix": "prefix",
"samplingRulesManifest": "/path/to/manifest",
"awsServiceHandlerManifest": "/path/to/manifest",
"awsSdkVersion": 2,
"maxStackTraceLength": 50,
"streamingThreshold": 100,
"traceIdInjection": true,
"pluginsEnabled": true,
"collectSqlQueries": false
}
```
### Especificação de configuração
A tabela a seguir descreve valores válidos para cada propriedade. Os nomes das propriedades diferenciam maiúsculas de minúsculas, mas as chaves não. Para propriedades que podem ser substituídas por variáveis de ambiente e propriedades do sistema, a ordem de prioridade é sempre variável de ambiente, depois propriedade do sistema e, em seguida, arquivo de configuração. Para obter informações sobre as propriedades que você pode substituir, consulte [Variáveis de ambiente](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars). Todos os campos são opcionais.
| Nome da propriedade | Tipo | Valores válidos | Description | Variável de ambiente | Propriedades do sistema | Padrão |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | String | Qualquer string | O nome do serviço instrumentado, conforme ele aparecerá no console do X-Ray. | AWS\_XRAY\_NOME\_DE\_RASTREAMENTO | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | String | LOG\_ERROR, IGNORE\_ERROR | A ação executada pelo agente quando ele tenta usar o contexto do segmento do X-Ray e não há nenhum presente. | AWS\_XRAY\_CONTEXTO\_AUSENTE | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\_ERROR |
| daemonAddress | String | Endereço IP e porta formatados ou lista de endereços TCP e UDP | O endereço que o agente usa para se comunicar com o daemon do X-Ray. | AWS\_XRAYENDEREÇO DO \_DAEMON | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1:2000 |
| tracingEnabled | Booliano | True, False | Permite a instrumentação pelo agente do X-Ray. | AWS\_XRAY\_RASTREAMENTO\_HABILITADO | com.amazonaws.xray.tracingEnabled | TRUE |
| samplingStrategy | String | CENTRAL, LOCAL, NONE, ALL | A estratégia de amostragem usada pelo agente. ALL captura todas as solicitações, NONE não captura nenhuma solicitação. Consulte as [regras de amostragem](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | N/D | N/D | CENTRAL |
| traceIdInjectionPrefixo | String | Qualquer string | Inclui o prefixo fornecido antes do rastreamento injetado IDs nos registros. | N/D | N/D | None (empty string) |
| samplingRulesManifest | String | Um caminho de arquivo absoluto | O caminho para um arquivo de regras de amostragem personalizado a ser usado como fonte de regras de amostragem para a estratégia de amostragem local ou as regras de fallback para a estratégia central. | N/D | N/D | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) |
| awsServiceHandlermanifesto | String | Um caminho de arquivo absoluto | O caminho para uma lista de permissões de parâmetros personalizados, o qual captura informações adicionais de clientes de SDK da AWS . | N/D | N/D | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) |
| awsSdkVersion | Inteiro | 1, 2 | Versão do [AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/index.html) que você está usando. Ignorado se `awsServiceHandlerManifest` também não estiver definido. | N/D | N/D | 2 |
| maxStackTraceComprimento | Inteiro | Números inteiros não negativos | O máximo de linhas de um rastreamento de pilha a serem registradas em um rastreamento. | N/D | N/D | 50 |
| streamingThreshold | Inteiro | Números inteiros não negativos | Depois que pelo menos tantos subsegmentos são fechados, eles são transmitidos para o daemon out-of-band para evitar que os pedaços sejam muito grandes. | N/D | N/D | 100 |
| traceIdInjection | Booleano | True, False | Permite a injeção de ID de rastreamento do X-Ray nos logs se as dependências e a configuração descritas na [configuração de registro em log](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) também forem adicionadas. Caso contrário, não faz nada. | N/D | N/D | TRUE |
| pluginsEnabled | Booleano | True, False | Ativa plug-ins que registram metadados sobre os AWS ambientes em que você está operando. Consulte [Plug-ins](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins). | N/D | N/D | TRUE |
| collectSqlQueries | Booleano | True, False | Registra strings de consulta SQL em subsegmentos de SQL com base no melhor esforço. | N/D | N/D | FALSE |
| contextPropagation | Booleano | True, False | Se verdadeiro, propaga automaticamente o contexto do X-Ray entre os segmentos. Caso contrário, usa Thread Local para armazenar contexto, e a propagação manual entre threads é necessária. | N/D | N/D | TRUE |
### Configuração de registro
O nível de log do agente do X-Ray pode ser configurado da mesma forma que o X-Ray SDK para Java. Consulte [Registro em log](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) para obter mais informações sobre como configurar o registro em log com o X-Ray SDK para Java.
### Instrumentação manual
Se você quiser realizar instrumentação manual além da instrumentação automática do agente, adicione o X-Ray SDK como uma dependência ao seu projeto. Observe que os filtros de servlet personalizados do SDK mencionados em [Rastrear solicitações de entrada](xray-sdk-java-filters.md) não são compatíveis com o agente do X-Ray.
**nota**
Você deve usar a versão mais recente do X-Ray SDK para realizar a instrumentação manual e, ao mesmo tempo, usar o agente.
Se você estiver trabalhando em um projeto Maven, adicione as dependências a seguir ao arquivo `pom.xml`.
```
com.amazonaws
aws-xray-recorder-sdk-core
2.11.0
```
Se você estiver trabalhando em um projeto Gradle, adicione as dependências a seguir ao arquivo `build.gradle`.
```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'
```
Você pode adicionar [subsegmentos personalizados](xray-sdk-java-subsegments.md), além de [anotações, metadados e usuário IDs](xray-sdk-java-segment.md) enquanto usa o agente, assim como faria com o SDK normal. Como o agente propaga automaticamente o contexto entre os threads, nenhuma solução alternativa para propagar o contexto deve ser necessária ao trabalhar com aplicativos de vários threads.
## Solução de problemas
Como o agente oferece instrumentação totalmente automática, pode ser difícil identificar a causa raiz quando você está enfrentando problemas. Se o agente do X-Ray não estiver funcionando conforme o esperado, analise os problemas e soluções a seguir. O agente do X-Ray e o respectivo SDK usam o Jakarta Commons Logging (JCL). Para ver a saída do registro em log, uma ponte para conectar o JCL ao back-end de registro em log deve estar no caminho de classe, como no exemplo a seguir: `log4j-jcl` ou `jcl-over-slf4j`.
### Problema: Eu habilitei o agente do Java no aplicativo, mas não vejo nada no console X-Ray
**O daemon do X-Ray está sendo executado na mesma máquina?**
Caso contrário, consulte a [documentação do daemon do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) para configurá-lo.
**Nos logs do aplicativo, você vê uma mensagem como “Inicializando o gravador do agente do X-Ray"?**
Se você adicionou corretamente o agente ao aplicativo, essa mensagem será registrada em log no nível INFO quando o aplicativo for iniciada, antes que as solicitações comecem a ser recebidas. Se essa mensagem não estiver ali, isso significa que o agente do Java não está sendo executado com seu processo Java. Confirme se você seguiu todas as etapas de configuração corretamente, sem erros de digitação.
**Nos registros do seu aplicativo, você vê várias mensagens de erro dizendo algo como “Suprimindo a exceção ausente do AWS X-Ray contexto”?**
Esses erros ocorrem porque o agente está tentando instrumentar solicitações downstream, como solicitações de AWS SDK ou consultas SQL, mas não conseguiu criar automaticamente um segmento. Se você observar muitos erros desse tipo, talvez o agente não seja a melhor ferramenta para seu caso de uso. Em vez disso, é aconselhável considerar a instrumentação manual com o X-Ray SDK. Como alternativa, você pode habilitar os [logs de depuração](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) do X-Ray SDK para ver o rastreamento da pilha em que as exceções de contexto ausente estão ocorrendo. Você pode agrupar essas partes do código com segmentos personalizados, o que deve resolver esses erros. Para ver um exemplo de empacotamento de solicitações subsequentes com segmentos personalizados, consulte o código de exemplo em [Instrumentar código de inicialização](scorekeep-startup.md).
### Problema: Alguns dos segmentos que eu espero não aparecem no console do X-Ray
**Suo aplicativo usa vários threads?**
Se alguns segmentos que você espera que sejam criados não estiverem aparecendo no console, os threads em segundo plano no aplicativo podem ser a causa. Se seu aplicativo executa tarefas usando encadeamentos em segundo plano que são “acionar e esquecer”, como fazer uma chamada única para uma função Lambda com AWS o SDK ou pesquisar periodicamente algum endpoint HTTP, isso pode confundir o agente enquanto ele propaga o contexto entre os encadeamentos. Para verificar se esse é o seu problema, habilite os logs de depuração do X-Ray SDK e verifique se há mensagens como: *Não emitindo segmento chamado porque ele gera subsegmentos em andamento*. Para contornar isso, você pode tentar unir os threads em segundo plano antes que o servidor retorne para garantir que todo o trabalho realizado neles seja registrado. Ou você pode definir a configuração `contextPropagation` do agente como `false` para desabilitar a propagação de contexto em threads em segundo plano. Se você fizer isso, precisará instrumentar manualmente esses threads com segmentos personalizados ou ignorar as exceções de contexto ausente que eles produzem.
**Você configurou regras de amostragem?**
Se segmentos aparentemente aleatórios ou inesperados estiverem aparecendo no console do X-Ray, ou os segmentos que você espera que estejam no console não estiverem aparecendo, você pode estar enfrentando um problema de amostragem. O agente do X-Ray aplica amostragem centralizada a todos os segmentos que ele cria, usando as regras do console do X-Ray. A regra de amostragem padrão é 1 segmento por segundo, mais 5% dos segmentos posteriores. Isso significa que os segmentos criados rapidamente com o agente podem não ser amostrados. Para resolver isso, você deve criar regras de amostragem personalizadas no console do X-Ray que tirem amostras adequadas dos segmentos desejados. Para obter mais informações, consulte [Amostragem](xray-console-sampling.md).