Java için Azure SDK'da izlemeyi yapılandırma

Bu makalede, izleme işlevselliğini tümleştirmek üzere Java için Azure SDK'sını yapılandırmaya yönelik genel bir bakış sağlanır.

OpenTelemetry SDK'sını kullanarak ve yapılandırarak veya OpenTelemetry uyumlu bir aracı kullanarak Azure istemci kitaplıklarında izlemeyi etkinleştirebilirsiniz. OpenTelemetry, bulutta yerel yazılımlar için telemetri verileri oluşturmaya, yakalamaya ve toplamaya yönelik popüler bir açık kaynak gözlemlenebilirlik çerçevesidir.

İzlemeyle ilgili iki temel kavram vardır: span ve izleme. Span, bir izdeki tek bir işlemi temsil eder. Yayılma alanı bir HTTP isteğini, uzaktan yordam çağrısını (RPC), veritabanı sorgusunu ve hatta kodunuzun izlediği yolu temsil edebilir. Bir iz, bir sistemdeki iş akışını gösteren bir segment veya aralık ağacıdır. İzlemeyi tek başına TraceID adlı benzersiz bir 16 baytlık diziyle ayırt edebilirsiniz. Bu kavramlar ve Bunların OpenTelemetry ile ilişkisi hakkında daha fazla bilgi için OpenTelemetry belgelerine bakın.

Azure Monitor Java aracısı ile Azure SDK izlemesi

Azure İzleyici Java işlem içi aracısını kullanarak, kod değişikliği yapmadan uygulamalarınızın izlenmesini etkinleştirebilirsiniz. Daha fazla bilgi için bkz. Java uygulamaları için OpenTelemetry tabanlı Azure Monitor otomatik izlemesi. Azure SDK desteği, aracı sürüm 3.2'den başlayarak varsayılan olarak etkindir.

OpenTelemetry aracısı ile Azure SDK çağrılarını izleme

OpenTelemetry Java ajansını kullanıyorsanız, Azure SDK enstrümantasyonu 1.12.0 sürümünden itibaren direkt olarak etkinleştirilir.

Daha fazla ayrıntı için, dışa aktarıcıları yapılandırma, manuel araç ekleme veya telemetriyi zenginleştirme konusunda bkz. Java için OpenTelemetry Araçları.

Uyarı

OpenTelemetry aracısı yapıtı kararlıdır, ancak kablo üzerinden telemetri kararlılığı garantileri sağlamaz. Bu durum, Azure SDK tarafından üretilen span adlarının ve öznitelik adlarının, aracı güncellediğinizde zamanla değişebileceği anlamına gelebilir. Daha fazla bilgi için bkz . Uyumluluk gereksinimleri.

Uygulamayı OpenTelemetry SDK ile el ile izleme (önizleme)

OpenTelemetry SDK'sını doğrudan kullanıyorsanız, SDK'yı ve aktarıcıyı tercih ettiğiniz arkadan için yapılandırdığınızdan emin olun. Daha fazla bilgi için OpenTelemetry belgelerine bakın.

Azure SDK izlemeyi etkinleştirmek için uygulamanıza en son com.azure:azure-core-tracing-opentelemetry paketleri ekleyin. Örneğin, Maven'da pom.xml dosyanıza aşağıdaki girdiyi ekleyin:

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

Uygulamayı şimdi çalıştırıyorsanız arka ucunuzda Azure SDK'sı spans'ı almanız gerekir. Ancak zaman uyumsuz çağrılarda Azure SDK ile uygulama yayılma alanları arasındaki bağıntı kesilebilir.

Varsayılan olarak Azure SDK, io.opentelemetry.context.Context.current()'yi OpenTelemetry tarafından örtük bir şekilde yeni uzanımlara üst olarak kullanır. Eşzamansız çağrılarda örtük bağlam aktarımı bozulur. OpenTelemetry aracıları bağlamın yayılmasına yardımcı olarak bu sorunu çözer, ancak OpenTelemetry SDK'sı bu özelliklere sahip değildir.

İz bağlamını açıkça iletin

Azure SDK, izleme bağlamını com.azure.core.util.Contexttrace-context anahtar altında açıkça geçirmenize olanak tanır. Açık izleme bağlamı sağladığınızda Azure SDK, uygulama ile Azure SDK'sı yayılma alanları arasında bağıntıya olanak tanıyan örtük bağlam yerine bunu kullanır.

Aşağıdaki örnekte, gelen bir web isteği el ile izlendiğinde, Uygulama Yapılandırması İstemci Kitaplığı bu isteğin kapsamında zaman uyumsuz olarak çağrılır.

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

//...

Azure SDK izleme kuralları

SDK'nın hangi yayılma aralıklarını ve öznitelikleri yaydığı öğrenmek için bkz. Azure SDK anlam kuralları belirtimi. Azure SDK (ve OpenTelemetry) semantik kuralları kararlı değildir ve gelecekte değişebilir.

Sonraki Adımlar

Java için Azure SDK'daki temel çapraz kesme işlevselliğini öğrendiğinize göre güvenli uygulamalar oluşturmayı öğrenmek için bkz. Java ve Azure Identity ile Azure kimlik doğrulaması .