Agente de instrumentação automática do AWS X-Ray para Java

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 aplicações 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 aplicações web Java baseadas em servlets e de solicitação e resposta. Se sua aplicação 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 do X-Ray é construído usando o kit de ferramentas Distributed Systems Comprehension ou DiSCo. O DiSCo é um framework de código aberto para criar agentes do Java que podem ser usados em sistemas distribuídos. Embora não seja necessário entender o DisCo para usar o agente X-Ray, você pode aprender mais sobre o projeto visitando sua página inicial em GitHub. 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.

Aplicação de exemplo

A aplicação eb-java-scorekeepda 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 a aplicação localmente ou usando recursos da AWS , siga as etapas no arquivo readme da aplicação de exemplo. As instruções sobre como usar a aplicação de exemplo para gerar rastreamentos do X-Ray estão no tutorial da aplicação de exemplo.

Conceitos básicos

Para começar a usar o agente do Java de instrumentação automática do X-Ray em sua aplicação, siga as etapas abaixo.

1. Execute o daemon do X-Ray no seu ambiente. Para obter mais informações, consulte Daemon do X-Ray.

2. Baixe a distribuição mais recente do agente. 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

3. Modifique os argumentos da JVM da aplicação 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:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

4. Para especificar como o nome da aplicação 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.

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

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. Consulte as Variáveis de ambiente para obter informações sobre as propriedades que você pode substituir. Todos os campos são opcionais.

Nome da propriedade	Tipo	Valores válidos	Descrição	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_TRACING_NAME	com.amazonaws.xray.strategy.tracingName	X RayInstrumentedService
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_CONTEXT_MISSING	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_XRAY_DAEMON_ADDRESS	com.amazonaws.xray.emitter.daemonAddress	127.0.0. 1:2000
tracingEnabled	Booleano	True, False	Permite a instrumentação pelo agente do X-Ray.	AWS_XRAY_TRACING_ENABLED	com.amazonaws.xray.tracingEnabled	VERDADEIRO
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.	N/D	N/D	CENTRAL
traceIdInjectionPrefixo	String	Qualquer string	Inclui o prefixo fornecido antes dos IDs de rastreamento injetados nos logs.	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
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
awsSdkVersion	Inteiro	1, 2	Versão do AWS SDK para Java 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 também forem adicionadas. Caso contrário, não faz nada.	N/D	N/D	VERDADEIRO
pluginsEnabled	Booleano	True, False	Ativa plug-ins que registram metadados sobre os AWS ambientes em que você está operando. Consulte Plug-ins.	N/D	N/D	VERDADEIRO
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	VERDADEIRO

Configuração de registro em log

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

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

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, além de anotações, metadados e IDs de usuário 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 aplicações 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 na aplicação, 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 para configurá-lo.

Nos logs da aplicação, você vê uma mensagem como “Inicializando o gravador do agente do X-Ray”?

Se você adicionou corretamente o agente à aplicação, essa mensagem será registrada em log no nível INFO quando a aplicação 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 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.

Problema: Alguns dos segmentos que eu espero não aparecem no console do X-Ray

Sua aplicação usa vários threads?

Se alguns segmentos que você espera que sejam criados não estiverem aparecendo no console, os threads em segundo plano na aplicação 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 <NOME> 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 Configurar regras de amostragem emExplore o console X-Ray.