Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 trace. 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 traço por si só através de uma sequência única 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, consulte 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 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ó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.