Instrumentação automática baseada em OpenTelemetry do Azure Monitor para aplicativos Java

  • Artigo
  • 12 minutos para o fim da leitura

Este artigo descreve como habilitar e configurar a oferta do Azure Monitor para Java baseada em OpenTelemetry. Ele pode ser usado para qualquer ambiente, incluindo o local. Depois de concluir as instruções deste artigo, você poderá usar o Application Insights do Azure Monitor para monitorar o seu aplicativo.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Faça a transição para cadeias de conexão para aproveitar as novas funcionalidades.

Introdução

A instrumentação automática do Java é habilitada por meio de alterações de configuração; nenhuma alteração de código é necessária.

Pré-requisitos

Habilitar o Application Insights do Azure Monitor

Esta seção mostra como baixar o arquivo jar de instrumentação automática.

Baixar o arquivo jar

Baixe o arquivo applicationinsights-agent-3.4.7.jar.

Aviso

Se você estiver atualizando de uma versão anterior do 3.x,

Começando com 3.4.0:

  • A amostragem limitada por taxa agora é padrão (se você não tiver configurado um percentual fixo anteriormente). Por padrão, ela capturará no máximo cinco solicitações por segundo (juntamente com suas dependências, rastreamentos e eventos personalizados). Confira a amostragem de percentual fixo se você quiser reverter para o comportamento anterior de capturar 100% das solicitações.

Começando com 3.3.0:

  • LoggingLevel não é capturado por padrão como parte da dimensão personalizada de Rastreamentos, pois esses dados já são capturados no campo SeverityLevel. Para obter detalhes sobre como reabilitar isso se necessário, confira as opções de configuração
  • Os registros de exceção não são mais registrados para dependências com falha, eles são registrados apenas para solicitações com falha.

Começando com 3.2.0:

  • As dependências "InProc" do controlador não são mais capturadas por padrão. Para obter detalhes sobre como reabilitar isso, confira as opções de configuração.
  • Os nomes de dependência do banco de dados agora são mais concisos, com a consulta completa (sanitizada) ainda presente no campo data. Agora os nomes de dependência HTTP estão mais descritivos. Essa alteração pode afetar os painéis ou alertas personalizados se eles dependiam dos valores anteriores. Para obter detalhes, confira as Notas sobre a versão 3.2.0.

Começando com 3.1.0:

  • Agora os nomes de operação e de telemetria de solicitação são prefixados pelo método HTTP, como GET e POST. Essa alteração pode afetar os painéis ou alertas personalizados se eles dependiam dos valores anteriores. Para obter detalhes, confira as Notas sobre a versão 3.1.0.

Apontar a JVM (Máquina Virtual Java) para o arquivo jar

Adicione -javaagent:"path/to/applicationinsights-agent-3.4.7.jar" aos argumentos da JVM de seu aplicativo.

Dica

Para obter ajuda com a configuração dos argumentos da JVM do aplicativo, confira Dicas para atualizar os argumentos da JVM.

Dica

Se você desenvolver um aplicativo Spring Boot, poderá substituir o argumento JVM por uma configuração programática. Mais aqui.

Definir a cadeia de conexão do Application Insights

  1. Há duas maneiras de apontar o arquivo jar para o recurso do Application Insights:

    • Defina uma variável de ambiente:

      APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>

    • Você também pode criar um arquivo de configuração chamado applicationinsights.json. Insira-o no mesmo diretório de applicationinsights-agent-3.4.7.jar com o conteúdo a seguir:

      {
  "connectionString": "Copy connection string from Application Insights Resource Overview"
}

  2. Encontre a cadeia de conexão no seu recurso do Application Insights.

    Captura de tela exibindo a visão geral e a cadeia de conexão do Application Insights.

Confirmar se os dados estão fluindo

Execute o aplicativo e abra a guia Recurso do Application Insights no portal do Azure. Pode levar alguns minutos para os dados aparecerem no portal.

Observação

Se você não conseguir executar o aplicativo ou não receber dados conforme o esperado, confira a seção Solução de problemas.

Captura de tela da guia Visão geral do Application Insights com solicitações de servidor e tempo de resposta do servidor em destaque.

Importante

Se você tiver dois ou mais serviços que emitem telemetria para o mesmo recurso do Application Insights, será necessário definir nomes de função de nuvem para representá-los corretamente no mapa do aplicativo.

Como parte do uso da instrumentação do Application Insights, coletamos e enviamos dados de diagnóstico para a Microsoft. Esses dados nos ajudam a executar e a aprimorar o Application Insights. É possível desabilitar a coleta de dados não essenciais. Para saber mais, confira Statsbeat no Azure Application Insights.

Opções de configuração

No arquivo applicationinsights.json, você também pode definir essas configurações:

  • Nome da função de nuvem
  • Instância de função de nuvem
  • amostragem
  • Métricas JMX
  • Dimensões Personalizadas
  • Processadores de Telemetria (pré-visualização)
  • Registro em log coletado automaticamente
  • Métricas de micrométricas coletadas automaticamente, que incluem métricas do atuador do Spring Boot
  • Pulsação
  • Proxy HTTP
  • Autodiagnóstico

Para mais informações, confira Opções de configuração.

Instrumentação Automática

O Java 3.x inclui a instrumentação automática a seguir.

Solicitações coletadas automaticamente

  • Consumidores JMS
  • Consumidores do Kafka
  • Netty
  • Quartz
  • Servlets
  • Agendamento do Spring

Observação

A instrumentação automática do Servlet e do Netty abrange a maioria dos serviços HTTP Java, incluindo Java EE, Jakarta EE, Spring Boot, Quarkus e Micronaut.

Dependências coletadas automaticamente

Dependências coletadas automaticamente, mais propagação de rastreamento distribuído downstream:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • Cliente JAX-RS
  • Jetty HttpClient
  • JMS
  • Kafka
  • Cliente Netty
  • OkHttp

Dependências coletadas automaticamente sem propagação de rastreamento distribuído downstream:

  • Cassandra
  • JDBC
  • MongoDB (assíncrono e síncrono)
  • Redis (Lettuce e Jedis)

Logs coletados automaticamente

  • Logback (incluindo propriedades de MDC)
  • Log4j (incluindo propriedades de Contexto de MDC/Thread)
  • JBoss Logging (incluindo propriedades de MDC)
  • java.util.logging

Métricas coletadas automaticamente

  • Micrometer, que inclui métricas do atuador do Spring Boot
  • Métricas JMX

SDKs do Azure

A telemetria emitida por esses SDKs do Azure é coletada automaticamente por padrão:

Modificar telemetria

Esta seção explica como modificar a telemetria.

Adicionar intervalos usando a anotação do OpenTelemetry

A maneira mais simples de adicionar os seus próprios intervalos é usando a anotação @WithSpan do OpenTelemetry.

Os intervalos preenchem as tabelas requests e dependencies no Application Insights.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-instrumentation-annotations-1.21.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-instrumentation-annotations</artifactId>
  <version>1.21.0</version>
</dependency>

  2. Use a anotação @WithSpan para emitir um intervalo sempre que o seu método for executado:

     import io.opentelemetry.instrumentation.annotations.WithSpan;

 @WithSpan(value = "your span name")
 public void yourMethod() {
 }

Por padrão, o intervalo acabará na tabela de dependências com o tipo de dependência InProc.

Se o seu método representa um trabalho em segundo plano que ainda não foi capturado pela instrumentação automática, é recomendável aplicar o atributo kind = SpanKind.SERVER à anotação @WithSpan para que ele acabe na tabela requests do Application Insights.

Adicionar intervalos usando a API do OpenTelemetry

Se a anotação @WithSpan do OpenTelemetry acima não atender às suas necessidades, adicione seus intervalos usando a API do OpenTelemetry.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Usar a GlobalOpenTelemetry classe para criar um Tracer

     import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.trace.Tracer;

 static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");

  3. Crie um intervalo, torne-o atual e, em seguida, encerre-o:

     Span span = tracer.spanBuilder("my first span").startSpan();
 try (Scope ignored = span.makeCurrent()) {
     // do stuff within the context of this 
 } catch (Throwable t) {
     span.recordException(t);
 } finally {
     span.end();
 }

Adicionar eventos de intervalo

Você pode usar opentelemetry-api para criar eventos de intervalo, que preenchem a tabela de rastreamentos no Application Insights. A cadeia de caracteres passada para addEvent() é salva no campo de mensagem dentro do rastreamento.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Adicione eventos de intervalo no código:

     import io.opentelemetry.api.trace.Span;

 Span.current().addEvent("eventName");

Adicionar atributos de intervalo

Você pode usar opentelemetry-api para adicionar atributos a intervalos. Esses atributos podem incluir a adição de uma dimensão comercial personalizada a sua telemetria. Você também pode usar atributos para definir campos opcionais no esquema do Application Insights, como ID de usuário ou IP do cliente.

Adicionar um ou mais atributos de extensão preencherá o campo customDimensions na tabela de solicitações, dependências, rastreamentos ou exceções.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Adicione dimensões personalizadas ao seu código:

     import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.common.AttributeKey;

 AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
 Span.current().setAttribute(attributeKey, "myvalue1");

Atualizar o status de intervalo e registrar exceções

Você pode usar opentelemetry-api para atualizar o status de um intervalo e registrar as exceções.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Defina o status como erro e registre uma exceção no código:

     import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.StatusCode;

 Span span = Span.current();
 span.setStatus(StatusCode.ERROR, "errorMessage");
 span.recordException(e);

Definir a ID de usuário

Preencha o campo ID de usuário na tabela de solicitações, dependências ou exceções.

Importante

Veja as leis de privacidade aplicáveis antes de configurar a ID de usuário autenticado.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Defina user_Id no seu código:

    import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

Obter a ID de rastreamento ou a ID do intervalo

Você pode usar opentelemetry-api para obter a ID de rastreamento ou a ID de intervalo. Essa ação pode ser feita para adicionar esses identificadores à telemetria de registro em log para aprimorar a correlação ao depurar e diagnosticar problemas.

Observação

Esse recurso está disponível apenas da versão 3.2.0 em diante.

  1. Adicione opentelemetry-api-1.0.0.jar (ou posterior) ao seu aplicativo:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Obtenha a ID de rastreamento de solicitação e a ID de intervalo em seu código:

    import io.opentelemetry.api.trace.Span;

Span span = Span.current();
String traceId = span.getSpanContext().getTraceId();
String spanId = span.getSpanContext().getSpanId();

Telemetria personalizada

Nossa meta no Application Insights Java 3.x é permitir que você envie a sua telemetria personalizada usando APIs padrão.

Atualmente damos suporte ao Micrometer, estruturas de log populares e ao SDK do Application Insights Java clássico. O Application Insights Java 3.x captura automaticamente a telemetria enviada por essas APIs e a correlaciona com a telemetria coletada automaticamente.

Telemetria personalizada compatível

A tabela a seguir representa os tipos de telemetria personalizados com suporte no momento, que você pode habilitar para complementar o agente do Java 3.x. Para resumir:

  • Há suporte para métricas personalizadas por meio do micrometer.
  • Há suporte para rastreamentos e exceções personalizadas por meio de estruturas de registro.
  • Há suporte para solicitações personalizadas, dependências, métricas e exceções por meio da API do OpenTelemetry.
  • Os tipos de telemetria restantes têm suporte por meio do SDK Clássico do Application Insights.
Tipos de telemetria personalizada Micrometer Logback, Log4j, JUL API do OpenTelemetry SDK clássico
Eventos personalizados Sim
Métricas personalizadas Sim Yes Sim
Dependências Sim Yes
Exceções Sim Sim Yes
Visualizações de página Yes
Requests Yes Yes
Rastreamentos Sim Sim

Enviar métricas personalizadas usando o Micrometer

  1. Adicione o Micrometer em seus aplicativos:

    <dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
  <version>1.6.1</version>
</dependency>

  2. Use o registro global do Micrometer para criar um medidor:

    static final Counter counter = Metrics.counter("test.counter");

  3. Use o contador para registrar as métricas:

    counter.increment();

  4. As métricas serão ingeridas na tabela customMetrics, com marcas capturadas na coluna . Você também pode exibir as métricas no Metrics Explorer no namespace de métrica "Métricas baseadas em log".

    Observação

    O Java do Application Insights substitui todos os caracteres não alfanuméricos (exceto traços) no nome da métrica do Micrometer por sublinhados, portanto, a métrica test.counter acima aparecerá como test_counter.

Envie exceções e rastreamentos personalizados usando a estrutura de registros que você quiser

Logback, Log4j e java.util.logging são instrumentados automaticamente. O registro em log executado por meio dessas estruturas de registros é coletado automaticamente como telemetria de rastreamento e exceção.

Por padrão, o log só é coletado quando ele é executado no nível INFO ou superior. Para alterar esse nível, consulte as opções de configuração.

O registro estruturado de log (anexar dimensões personalizadas aos logs) pode ser realizado destas maneiras:

Enviar telemetria personalizada usando o SDK Clássico do Application Insights

  1. Adicione o applicationinsights-core ao seu aplicativo:

    <dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.4.7</version>
</dependency>

  2. Crie um TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();

  3. Use o cliente para enviar telemetria personalizada:

    Eventos
    telemetryClient.trackEvent("WinGame");
    Métricas
    telemetryClient.trackMetric("queueLength", 42.0);
    Dependências
    boolean success = false;
long startTime = System.currentTimeMillis();
try {
    success = dependency.call();
} finally {
    long endTime = System.currentTimeMillis();
    RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
    telemetry.setSuccess(success);
    telemetry.setTimestamp(new Date(startTime));
    telemetry.setDuration(new Duration(endTime - startTime));
    telemetryClient.trackDependency(telemetry);
}
    Logs
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    Exceções
    try {
    ...
} catch (Exception e) {
    telemetryClient.trackException(e);
}

Solução de problemas

Confira o artigo de solução de problemas dedicado.

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

Os SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST para nossos pontos de extremidade de ingestão. Você pode testar a conectividade do servidor Web ou do computador host do aplicativo para os pontos de extremidade do serviço de ingestão usando clientes REST brutos do PowerShell ou comandos curl. Confira Solucionar problemas de telemetria de aplicativo ausente no Application Insights do Azure Monitor.

Notas de versão

Confira as notas sobre a versão no GitHub.

Suporte

Para obter suporte:

Comentários sobre o OpenTelemetry

Para fornecer comentários:

Próximas etapas