Configurar o rastreamento no SDK do Azure para Java

Artigo
10/23/2023

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

Usando um agente Java em processo do Azure Monitor, você pode habilitar o monitoramento de seus aplicativos sem alterações 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.

Rastreando chamadas do SDK do Azure com o agente OpenTelemetry

Se você usar o agente Java OpenTelemetria, 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.

Observação

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 com o tempo se você atualizar o agente. Para obter mais informações, consulte Requisitos de compatibilidade.

Instrumentar 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 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 , implicitamente propagado pelo OpenTelemetry, como um pai para novas transgressões. Em chamadas assíncronas, quebras de propagação de contexto implícitas. Os agentes OpenTelemetry resolvem esse problema ajudando a propagação do contexto, mas o SDK do OpenTelemetry não tem esses recursos.

Passar 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 as extensões do aplicativo e 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 do 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 abrangências 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 do 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