Configurare la traccia in Azure SDK per Java

Articolo
10/23/2023

Questo articolo offre una panoramica di come configurare Azure SDK per Java per integrare la funzionalità di traccia.

È possibile abilitare la traccia nelle librerie client di Azure usando e configurando OpenTelemetry SDK o usando un agente compatibile con OpenTelemetry. OpenTelemetry è un diffuso framework di osservabilità open source per la generazione, l'acquisizione e la raccolta di dati di telemetria per il software nativo del cloud.

Esistono due concetti chiave correlati alla traccia: span e trace. Un intervallo rappresenta una singola operazione in una traccia. Un intervallo può rappresentare una richiesta HTTP, una chiamata di procedura remota (RPC), una query di database o anche il percorso che il codice accetta. Una traccia è un albero di intervalli che mostrano il percorso di lavoro attraverso un sistema. È possibile distinguere una traccia autonomamente da una sequenza a 16 byte univoca denominata TraceID. Per altre informazioni su questi concetti e su come sono correlati a OpenTelemetry, vedere la documentazione di OpenTelemetry.

Traccia di Azure SDK con l'agente Java di Monitoraggio di Azure

Usando un agente Java in-process di Monitoraggio di Azure, è possibile abilitare il monitoraggio delle applicazioni senza modifiche al codice. Per altre informazioni, vedere Strumentazione automatica basata su OpenTelemetry di Monitoraggio di Azure per le applicazioni Java. Il supporto di Azure SDK è abilitato per impostazione predefinita a partire dalla versione 3.2 dell'agente.

Traccia delle chiamate di Azure SDK con l'agente OpenTelemetry

Se si usa l'agente Java OpenTelemetry, la strumentazione di Azure SDK è abilitata a partire dalla versione 1.12.0.

Per altre informazioni su come configurare gli utilità di esportazione, aggiungere strumentazione manuale o arricchire i dati di telemetria, vedere Strumentazione OpenTelemetry per Java.

Nota

L'artefatto dell'agente OpenTelemetry è stabile, ma non fornisce garanzie di stabilità di telemetria over-the-wire, che possono causare nomi di intervalli e nomi di attributi prodotti da Azure SDK che potrebbero cambiare nel tempo se si aggiorna l'agente. Per altre informazioni, vedere Requisiti di compatibilità.

Instrumentare manualmente l'applicazione con OpenTelemetry SDK (anteprima)

Se si usa direttamente OpenTelemetry SDK, assicurarsi di configurare l'SDK e l'utilità di esportazione per il back-end preferito. Per altre informazioni, vedere la documentazione di OpenTelemetry.

Per abilitare la traccia di Azure SDK, aggiungere i pacchetti più recenti com.azure:azure-core-tracing-opentelemetry all'applicazione. Ad esempio, in Maven aggiungere la voce seguente al file pom.xml :

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

Se si esegue ora l'applicazione, è necessario ottenere gli intervalli di Azure SDK nel back-end. Tuttavia, con chiamate asincrone, la correlazione tra Azure SDK e gli intervalli di applicazioni può essere interrotta.

Per impostazione predefinita, Azure SDK usa io.opentelemetry.context.Context.current(), propagato in modo implicito da OpenTelemetry, come elemento padre a nuovi intervalli. Nelle chiamate asincrone, la propagazione implicita del contesto si interrompe. Gli agenti OpenTelemetry risolveranno questo problema aiutando la propagazione del contesto, ma OpenTelemetry SDK non dispone di tali funzionalità.

Passare il contesto di traccia in modo esplicito

Azure SDK consente di passare il contesto di traccia in modo esplicito sotto com.azure.core.util.Context la trace-context chiave. Quando si specifica un contesto di traccia esplicito, Azure SDK lo usa invece di quello implicito, che abilita la correlazione tra l'applicazione e gli intervalli di Azure SDK.

Nell'esempio seguente, quando una richiesta Web in ingresso viene tracciata manualmente, la libreria client di configurazione dell'applicazione viene chiamata in modo asincrono nell'ambito di questa richiesta.

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

//...

Convenzioni di traccia di Azure SDK

Per informazioni sugli intervalli e gli attributi generati dall'SDK, vedere la specifica delle convenzioni semantiche di Azure SDK. Le convenzioni semantiche di Azure SDK (e OpenTelemetry) non sono stabili e potrebbero cambiare in futuro.

Passaggi successivi

Ora che si ha familiarità con le principali funzionalità trasversali in Azure SDK per Java, vedere Autenticazione di Azure con Java e Identità di Azure per informazioni su come creare applicazioni sicure.

Condividi tramite