Configurar o rastreamento no SDK do Azure para Java

Este artigo fornece 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. OpenTelemetry é uma estrutura de observabilidade de código aberto popular para gerar, capturar e coletar dados de telemetria para software nativo da nuvem.

Existem dois conceitos-chave relacionados com o rastreio: span e trace. Um span representa uma única operação em um rastreamento. Uma extensão pode representar uma solicitação HTTP, uma chamada de procedimento remoto (RPC), uma consulta de banco de dados ou até mesmo o caminho que seu código toma. Um traço é uma árvore de vãos que mostra o caminho do trabalho através de 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 com o OpenTelemetry, consulte a documentação do OpenTelemetry .

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

Usando um agente em processo Java do Azure Monitor, você pode habilitar o monitoramento de seus aplicativos sem alterações de código. Para obter mais informações, consulte Azure Monitor OpenTelemetry-based auto-instrumentation for Java applications. O suporte do SDK do Azure é habilitado por padrão a partir da versão 3.2 do agente.

Rastreando chamadas do SDK do Azure com o agente OpenTelemetry

Se você usar o agente Java OpenTelemetry , a instrumentação do SDK do Azure será habilitada imediatamente 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 OpenTelemetry Instrumentation for Java.

Nota

O artefato do agente OpenTelemetry é estável, mas não fornece garantias de estabilidade de telemetria over-the-wire, o que pode causar nomes de span e nomes de atributos produzidos pelo SDK do Azure que podem mudar ao longo do tempo se você atualizar o agente. Para obter mais informações, consulte Requisitos de compatibilidade.

Instrumente manualmente o aplicativo com o OpenTelemetry SDK (visualização)

Se você usar o OpenTelemetry SDK 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, deverá obter extensões do SDK do Azure em seu back-end. No entanto, com chamadas assíncronas, a correlação entre o SDK do Azure e as extensões de aplicativo pode ser quebrada.

Por padrão, o SDK do Azure usa io.opentelemetry.context.Context.current()o , propagado implicitamente pelo OpenTelemetry, como pai para novas extensões . Em chamadas assíncronas, a propagação de contexto implícito é interrompida. Os agentes OpenTelemetry resolvem esse problema ajudando a propagação do contexto, 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 sob com.azure.core.util.Context a trace-context chave. 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 as extensões 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 extensões 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óximos passos

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