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.

Pode ativar o rastreamento nas bibliotecas cliente do Azure usando e configurando o SDK 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.

Dois conceitos principais relacionados com o rastreio são span e trace. Um span representa uma única operação num traço. 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çado é uma árvore de segmentos que mostra o trajeto do trabalho através de um sistema. Uma sequência única de 16 bytes chamada TraceID distingue um traço. Para obter mais informações sobre esses conceitos e como eles se relacionam com o OpenTelemetry, consulte a [documentação do OpenTelemetry](https://opentelemetry.io/docs/).

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 instrumentação automática baseada no OpenTelemetry para aplicações Java do Azure Monitor. O suporte do SDK do Azure é habilitado por padrão a partir da versão 3.2 do agente.

Rastreio do SDK do Azure com o agente OpenTelemetry

Se usar o agente OpenTelemetry Java, a instrumentação do SDK do Azure está ativada 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.

Instrumente manualmente a aplicação com o SDK do OpenTelemetry (prévia)

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 executares a aplicação agora, deverás obter spans do SDK do Azure no teu backend. No entanto, com chamadas assíncronas, a correlação entre o SDK do Azure e os spans de aplicação pode estar 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 na propagação do contexto, mas o SDK do OpenTelemetry não tem essas capacidades.

Passar o contexto de rastreamento explicitamente

O SDK do Azure permite passar o contexto de rastreamento explicitamente sob a chave com.azure.core.util.Context através de 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 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 spans 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 está familiarizado com as funcionalidades essenciais e transversais no SDK do Azure para Java, veja Autenticação do Azure com Java e Identidade do Azure para aprender a criar aplicações seguras.