Configurar o rastreamento no SDK do Azure para Java

Artigo
10/03/2024

Este artigo apresenta uma visão geral de como configurar o SDK do Azure para Java para integrar a funcionalidade de rastreamento.

Você pode habilitar o rastreamento em bibliotecas de cliente do Azure usando e configurando o SDK do OpenTelemetry ou usando um agente compatível com OpenTelemetry. O OpenTelemetry é uma estrutura popular de observabilidade de software livre para gerar, capturar e coletar dados de telemetria para programas de software nativos de nuvem.

Há dois conceitos principais relacionados ao rastreamento: span e rastreamento. Um span representa uma operação em um rastreamento. Um span pode representar uma solicitação HTTP, uma RPC (chamada de procedimento remoto), uma consulta de banco de dados ou até mesmo o caminho que seu código segue. Um rastreamento é uma árvore de spans que mostra o caminho do trabalho por um sistema. Você pode distinguir um rastreamento por conta própria por uma sequência exclusiva de 16 bytes chamada TraceID. Para obter mais informações sobre esses conceitos e como eles se relacionam ao OpenTelemetry, confira a documentação do OpenTelemetry.

Rastreamento do SDK do Azure com o agente Java do Azure Monitor

Ao usar um agente Java em andamento do Azure Monitor, você pode habilitar o monitoramento de seus aplicativos sem nenhuma alteração de código. Para mais informações, confira Instrumentação automática baseada no OpenTelemetry do Azure Monitor para aplicativos Java. O suporte ao SDK do Azure é habilitado por padrão a partir da versão 3.2 do agente.

Rastrear chamadas do SDK do Azure com o agente OpenTelemetry

Se você usar o agente Java do OpenTelemetry, a instrumentação do SDK do Azure será habilitada pronta para uso a partir da versão 1.12.0.

Para obter mais detalhes sobre como configurar exportadores, adicionar instrumentação manual ou enriquecer a telemetria, consulte Instrumentação do OpenTelemetry para Java.

Observação

O artefato do agente OpenTelemetry é estável, mas não fornece garantias de estabilidade de telemetria pela conexão, o que pode fazer com que nomes de intervalo e nomes de atributo produzidos pelo SDK do Azure possam ser alterados ao longo do tempo se você atualizar o agente. Para obter informações, consulte Requisitos de compatibilidade.

Instrumentar manualmente o aplicativo com o SDK do OpenTelemetry (versão preliminar)

Se você usar o SDK do OpenTelemetry diretamente, certifique-se de configurar o SDK e o exportador para o back-end de sua escolha. Para obter mais informações, consulte a documentação do OpenTelemetry.

Para habilitar o rastreamento do SDK do Azure, adicione os pacotes mais recentes com.azure:azure-core-tracing-opentelemetry ao seu aplicativo. Por exemplo, no Maven, adicione a seguinte entrada ao seu arquivo pom.xml:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

Se você executar o aplicativo agora, deve obter intervalos do SDK do Azure em seu back-end. No entanto, com chamadas assíncronas, a correlação entre o SDK do Azure e os intervalos de aplicativos pode ser interrompida.

Por padrão, o SDK do Azure usa io.opentelemetry.context.Context.current(), propagado implicitamente pelo OpenTelemetry, como pai para novos intervalos. Em chamadas assíncronas, a propagação implícita de contexto é interrompida. Os agentes do OpenTelemetry resolvem esse problema ajudando o contexto a se propagar, mas o SDK do OpenTelemetry não tem esses recursos.

Passar o contexto de rastreamento explicitamente

O SDK do Azure permite passar o contexto de rastreamento explicitamente por meio de com.azure.core.util.Context sob a chave trace-context. Quando você fornece contexto de rastreamento explícito, o SDK do Azure o usa em vez do implícito, o que permite a correlação entre o aplicativo e os intervalos do SDK do Azure.

No exemplo a seguir, quando uma solicitação da Web de entrada é rastreada manualmente, a Biblioteca de Cliente de Configuração de Aplicativo é chamada de forma assíncrona no escopo dessa solicitação.

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Convenções de rastreamento do SDK do Azure

Para descobrir quais intervalos e atributos o SDK emite, consulte a especificação de convenções semânticas do SDK do Azure. As convenções semânticas do SDK do Azure (e OpenTelemetry) não são estáveis e podem mudar no futuro.

Próximas etapas

Agora que você está familiarizado com a funcionalidade cruzada principal no SDK do Azure para Java, confira Autenticação do Azure com Java e Azure Identity para saber como criar aplicativos seguros.

Compartilhar via