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

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 HTTP solicitações, AWS SDK solicitações e SQL consultas downstream do Apache feitas usando um driver. JDBC O agente propaga o contexto do X-Ray, incluindo todos os segmentos e subsegmentos ativos, em todos os threads. Todas as configurações e versatilidade do X-Ray ainda SDK estão disponíveis com o agente 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 seu aplicativo usa uma estrutura assíncrona ou não está bem modelado como um serviço de solicitação-resposta, talvez você queira considerar a instrumentação manual com o. SDK 

O agente X-Ray é construído usando o kit de ferramentas Distributed Systems Comprehension, ou D. iSCo D iSCo é 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 D iSCo 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.

Configuração

O agente X-Ray é configurado por um JSON arquivo 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 propriedades que você pode substituir, consulteVariáveis de ambiente. Todos os campos são opcionais.

Configuração de registro em log

O nível de log do agente 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 for 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 SDK de servlet personalizados mencionados em Rastreando solicitações de entrada não são compatíveis com o agente X-Ray.

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 usuário IDs enquanto usa o agente, assim como faria com o normal. SDK 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 X-Ray e SDK use o Jakarta Commons Logging ()JCL. Para ver a saída do registro, certifique-se de que uma ponte conectada JCL ao seu back-end de registro esteja no caminho de classe, como no exemplo a seguir: ou. log4j-jcl 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 ao seu aplicativo, essa mensagem será registrada no INFO nível quando o aplicativo for iniciado, antes de começar a receber solicitações. 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 posteriores, como AWS SDK solicitações ou SQL consultas, mas não conseguiu criar automaticamente um segmento. Se você observar muitos desses erros, o agente pode não ser a melhor ferramenta para seu caso de uso e talvez você queira considerar a instrumentação manual com o SDK X-Ray. Como alternativa, você pode ativar os registros de SDK depuração do X-Ray para ver o rastreamento da pilha de onde as exceções sem contexto 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 threads em segundo plano que são “disparar e esquecer”, como fazer uma chamada única para uma função Lambda com AWS SDK o. ou pesquisar HTTP algum endpoint periodicamente, isso pode confundir o agente enquanto ele propaga o contexto entre os encadeamentos. Para verificar se esse é o seu problema, habilite os registros de SDK depuração do X-Ray e verifique se há mensagens como: Não está emitindo um segmento chamado < NAME >, pois 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.