System.Net kitaplıklarında dağıtılmış izleme

Dağıtılmış izleme, mühendislerin uygulamalardaki hataları ve performans sorunlarını, özellikle de birden çok makineye veya işleme dağıtılmış olanları yerelleştirmelerine yardımcı olan bir tanılama tekniğidir. Bu teknik, farklı bileşenler tarafından yapılan işleri birbirine bağlayarak ve eşzamanlı istekler için uygulamanın yaptığı diğer işlerden ayırarak bir uygulama aracılığıyla istekleri izler. Örneğin, tipik bir web hizmetine yönelik bir istek önce bir yük dengeleyici tarafından alınıp ardından bir web sunucusu işlemine iletilebilir ve bu işlem veritabanına birkaç sorgu yapar. Dağıtılmış izleme, mühendislerin bu adımlardan herhangi birinin başarısız olup olmadığını ve her adımın ne kadar sürdüğünü ayırt etmesini sağlar. Her adım çalıştırıldığında oluşturulan iletileri de günlüğe kaydedebilir.

.NET'teki izleme sistemi OpenTelemetry (OTel) ile çalışacak şekilde tasarlanmıştır ve verileri izleme sistemlerine aktarmak için OTel kullanır. .NET'te izleme, System.Diagnostics API'leri kullanılarak uygulanır ve bir iş birimi System.Diagnostics.Activity sınıfı ile temsil edilir; ayrıca bu, OTel yayılmasına yanikapsamına karşılık gelir. OpenTelemetry, anlam kuralları olarak bilinen öznitelikleriyle (etiketler) birlikte aralıklar (etkinlikler) için sektör genelinde bir standart adlandırma şeması tanımlar. .NET telemetrisi, mümkün olan her yerde mevcut anlamsal kuralları kullanır.

Enstrümantasyon

İzlemeleri yaymak için, System.Net kitaplıkları, gerçekleştirilen işi izlemek için Activity nesneler oluşturan yerleşik ActivitySource kaynaklarıyla izlenir. Etkinlikler yalnızca ActivitySourceabonesi olan dinleyiciler varsa oluşturulur.

.NET sürümleriyle birlikte yerleşik araçlar gelişti.

• .NET 8 ve önceki sürümlerde araç gereç kullanımı, boş bir HTTP istemci isteği etkinliğinin oluşturulmasıyla sınırlıdır. Kullanıcıların, etkinliği kullanışlı izler yaymak için gereken bilgilerle (örneğin, etiketler) doldurmak amacıyla OpenTelemetry.Instrumentation.Http kitaplığına güvenmeleri gerektiği anlamına gelir.
• .NET 9, HTTP istemci isteği etkinliğinde OTel HTTP istemci semantik kurallarına göre adı, durumu, özel durum bilgilerini ve en önemli etiketleri yayarak izlemenin genişletilmesine neden oldu. Bu, zenginleştirme gibi daha gelişmiş özellikler gerekmediği sürece .NET 9+ için OpenTelemetry.Instrumentation.Http bağımlılığının atlanabileceği anlamına gelir.
• .NET 9 ayrıca bağlantı sorunlarını tanılamayı desteklemek için System.Net kitaplıklarına yeni etkinlikler ekleyerek deneysel bağlantı izlemekullanıma sunulmuştur.

System.Net izlemelerini toplama

en düşük düzeydeizleme koleksiyonu, kullanıcı tanımlı mantık içeren ActivityListener nesneleri kaydeden AddActivityListener yöntemi aracılığıyla desteklenir.

Ancak bir uygulama geliştiricisi olarak, izlemeleri toplamak, dışarı aktarmak ve izlemek için OpenTelemetry .NET SDK tarafından sağlanan özellikleri temel alan zengin ekosisteme güvenmeyi tercih edebilirsiniz.

• OTel ile iz toplama hakkında temel bilgi edinmek için OpenTelemetry kullanarak izleri toplama kılavuzumuzabakın.
• üretim zamanı izleme toplama ve izleme için OpenTelemetry'yi Prometheus, Grafana ve Jaeger veya Azure İzleyici ve Application Insightsile kullanabilirsiniz. Ancak bu araçlar oldukça karmaşıktır ve geliştirme zamanında kullanılması zor olabilir.
• geliştirirken izleme verisi toplama ve izleme için, uygulamanızda dağıtılmış izlemeyi başlatmak ve sorunları yerel olarak tanılamak için basit ama genişletilebilir bir yol sunan .NET Aspire kullanmanızı öneririz.
• Aspire düzenlemesi olmadan Aspire Service Defaults projesini yeniden kullanmak da mümkündür. Bu, ASP.NET projelerinizde OpenTelemetry izleme ve ölçümlerini tanıtmak ve yapılandırmak için kullanışlı bir yoldur.

.NET Aspire ile izleri toplama

ASP.NET uygulamalarında izlemeleri ve ölçümleri toplamanın basit bir yolu .NET Aspirekullanmaktır. .NET Aspire, dağıtılmış uygulamalar oluşturmayı ve bunlarla çalışmayı kolaylaştırmak için .NET'e yönelik bir uzantı kümesidir. .NET Aspire kullanmanın avantajlarından biri, telemetrinin .NET için OpenTelemetry kitaplıkları kullanılarak yerleşik olmasıdır.

.NET Aspire için varsayılan proje şablonları ServiceDefaults bir proje içerir. .NET Aspire çözümündeki her hizmetin Service Defaults projesine bir başvurusu vardır. Hizmetler bunu OTel'i ayarlamak ve yapılandırmak için kullanır.

Service Defaults proje şablonu OTel SDK, ASP.NET, HttpClient ve Runtime Instrumentation paketlerini içerir. Bu enstrümantasyon bileşenleri Extensions.cs dosyasında yapılandırılır. Aspire Panosu'nda telemetri görselleştirmesini desteklemek için, Hizmet Varsayılanları projesi varsayılan olarak OTLP verme işlemini de içerir.

Aspire Panosu, telemetri gözlemini yerel hata ayıklama döngüsüne getirerek geliştiricilerin uygulamaların telemetri ürettiğinden emin olmasını sağlayacak şekilde tasarlanmıştır. Telemetri görselleştirmesi, bu uygulamaları yerel olarak tanılamaya da yardımcı olur. Hizmetler arasındaki çağrıları gözlemleyebilmek, üretimdeki hata ayıklama zamanında olduğu kadar yararlıdır. .NET Aspire panosu, Visual Studio'dan AppHost projeyi F5 veya komut satırından AppHost projeyi dotnet run başlattığınızda otomatik olarak açılır.

Aspire Panosu

.NET Aspire hakkında daha fazla bilgi için bkz:

• Aspire'a Genel Bakış
• Aspire 'de Telemetri
• Aspire Gösterge Paneli

.NET Aspire Orchestration olmadan Hizmet Varsayılanları projelerini yeniden kullanma

Aspire Service Defaults projesi, düzenleme için AppHost gibi .NET Aspire geri kalanını kullanmasa bile ASP.NET projeler için OTel'i yapılandırmanın kolay bir yolunu sağlar. Hizmet Varsayılanları projesi Visual Studio veya dotnet newaracılığıyla bir proje şablonu olarak kullanılabilir. OTel'i yapılandırır ve OTLP ihracatçısını kurar. Ardından OTel ortam değişkenlerini kullanarak OTLP uç noktasını telemetri gönderecek şekilde yapılandırabilir ve uygulamanın kaynak özelliklerini sağlayabilirsiniz.

.NET Aspire dışında ServiceDefaults kullanma adımları şunlardır:

1. Visual Studio'da Yeni Proje Ekle'yi kullanarak çözüme ServiceDefaults projesini ekleyin veya dotnet newkullanın:

   dotnet new aspire-servicedefaults --output ServiceDefaults
   

2. ASP.NET uygulamanızdan ServiceDefaults projesine başvurun. Visual Studio'da >Proje Referansı Ekle'ü seçin ve ardından ServiceDefaults projesini seçin.

3. Uygulama oluşturucu başlatmanızın bir parçası olarak OpenTelemetry kurulum işlevini ConfigureOpenTelemetry() çağırın.

   var builder = WebApplication.CreateBuilder(args)
   builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
   var app = builder.Build();
   app.MapGet("/", () => "Hello World!");
   app.Run();
   

Ayrıntılı rehber için bkz. Örnek: OTLP ve tek başına Aspire Gösterge Tablosu ile OpenTelemetry kullanma.

Deneysel bağlantı izleme

HttpClient sorunlarını veya performans sorunlarını giderirken, HTTP istekleri gönderirken zamanın nereye harcandığını görmek çok önemli olabilir. HTTP bağlantısı kurulumu esnasında sorun genellikle, DNS araması, TCP bağlantısı ve TLS el sıkışmasını içeren işlemler sırasında meydana gelir.

.NET 9, bağlantı kuruluşunun DNS, TCP ve TLS aşamalarını temsil eden üç alt yayılım içeren bir HTTP connection setup span ekleyen deneysel bağlantı izleme özelliğini tanıttı. Bağlantı izlemenin HTTP bölümü SocketsHttpHandleriçinde uygulanır, yani etkinlik modelinin temel alınan bağlantı havuzu davranışına saygı duyması gerekir.

.NET 9, ayrıntılı bağlantı bilgilerinin toplanmasına olanak tanımak için aşağıdaki kapsamları kullanıma sunar:

Bu aralıklar, yüksek iş yüklerine sahip üretim senaryolarında 7/24 kullanım için çok ayrıntılıdır; gürültülü olur ve normalde bu izleme düzeyine ihtiyaç duyulmaz. Ancak, bağlantı sorunlarını tanılamaya veya ağ ve bağlantı gecikme süresinin hizmetlerinizi nasıl etkilediğini daha iyi anlamaya çalışıyorsanız, bunlar başka yollarla toplanması zor içgörüler sağlar.

Experimental.System.Net.Http.Connections ActivitySource etkinleştirildiğinde, HTTP client requestistek sunan bağlantıya karşılık gelen HTTP connection_setup yayılma alanının bağlantısını içerir. HTTP bağlantısı uzun ömürlü olabileceğinden, bu durum istek etkinliklerinin her birinden bağlantı aralığına birçok bağlantı yapılmasına neden olabilir. Bazı APM izleme araçları, görünümlerini oluşturmak için aralıklar arasındaki bağlantıları agresif bir şekilde izler ve bu nedenle bu aralığı dahil etmek, araçlar çok sayıda bağlantıyı hesaba katacak şekilde tasarlanmadığında sorunlara sebep olabilir.

Aşağıdaki diyagramda span'ların davranışı ve bunların ilişkisi gösterilmektedir:

İzlenecek yol: .NET 9'da deneysel bağlantı izlemeyi kullanma

Bu kılavuzda bağlantı izlemeyi göstermek için .NET 9 Aspire Starter Uygulaması kullanılır, ancak diğer izleme araçlarıyla da kolayca ayarlanabilir. Önemli adım ActivitySources'un etkinleştirilmesidir.

1. dotnet newkullanarak bir .NET Aspire 9 Başlangıç Uygulaması oluşturun:

   dotnet new aspire-starter-9 --output ConnectionTracingDemo
   

   Veya Visual Studio'da:

   

2. ServiceDefaults projesinde Extensions.cs açın ve izleme yapılandırması geri çağırmasında bağlantı için ActivitySources'u ekleyen ConfigureOpenTelemetry yöntemini düzenleyin:

   .WithTracing(tracing =>
   {
       tracing.AddAspNetCoreInstrumentation()
           // Instead of using .AddHttpClientInstrumentation()
           // .NET 9 allows to add the ActivitySources directly.
           .AddSource("System.Net.Http")
           // Add the experimental connection tracking ActivitySources using a wildcard.
           .AddSource("Experimental.System.Net.*");
   });
   

3. Çözümü başlatın. Bu, .NET Aspire Panosuaçmalıdır.

4. webfrontend uygulamasının Hava Durumu sayfasına gidin ve apiservice'ye yönelik bir HttpClient isteği oluşturun.

5. Kontrol Paneline dönün ve İzlemeler sayfasına gidin. webfrontend: GET /weather izini açın.

   Aspire Panosunda HttpClient Spans

Bağlantı enstrümantasyonu etkinken HTTP istekleri yapıldığında, istemci istek kapsamlarında aşağıdaki değişiklikleri görmelisiniz.

• Bağlantı kurulması gerekiyorsa veya uygulama bağlantı havuzundan bağlantı bekliyorsa, bağlantının yapılmasını bekleme gecikmesini temsil eden ek bir HTTP wait_for_connection aralığı gösterilir. Bu, kodda yapılan HttpClient isteği arasındaki gecikmeleri ve isteğin işlenmesinin gerçekten ne zaman başladığını anlamanıza yardımcı olur. Önceki resimde:
  • Seçilen yayılma alanı HttpClient isteğidir.
  • Aşağıdaki süre, isteğin bağlantı kurulmasını beklerken harcadığı zamanı temsil eder.
  • Sarı renkteki son yayılma alanı, isteği işleyen hedeftendir.
• HttpClient aralığı, istek tarafından kullanılan HTTP bağlantısını oluşturma etkinliğini temsil eden HTTP connection_setup aralığına bir bağlantıya sahip olacak.

Aspire Panosu'nda bağlantı kurulum

Daha öncebelirtildiği gibi, HTTP connection_setup span, yaşam süresi her istemci isteğinden bağımsız olan ve kendi TraceId'si bulunan ayrı bir alandır. Bu bölüm genellikle DNS lookup, (TCP) socket connectve TLS client handshakealt bölümlerini içerir.

Zenginleşme

Bazı durumlarda, mevcut System.Net izleme işlevselliğini artırmak gerekir. Bu genellikle yerleşik etkinliklere ek etiketler/öznitelikler eklemek anlamına gelir. Buna zenginleştirmeadı verilir.

OpenTelemetry izleme kitaplığındaki Zenginleştirme API'si

HTTP istemci isteği etkinliğine ek etiketler/öznitelikler eklemek için en basit yaklaşım, OpenTelemetry HttpClient ve HttpWebRequest izleme kitaplığının HttpClient zenginleştirme API'lerini kullanmaktır. Bunun için OpenTelemetry.Instrumentation.Http paketine bağımlılık yapılması gerekir.

El ile zenginleştirme

HTTP client request etkinliğinin zenginleştirilmesini el ile uygulamak mümkündür. Bunun için, etkinlik bitmeden önce talep faaliyetinin kapsamında çalışmakta olan kodda Activity.Current'a erişmeniz gerekir. Bu, IObserver<DiagnosticListener>'ı uygulayarak ve ağ etkinliği yaşandığında bildirim almak için AllListeners'e abone olarak yapılabilir. Aslında, OpenTelemetry HttpClient ve HttpWebRequest izleme kitaplığı bu şekilde uygulanır. Kod örneği için DiagnosticSourceSubscriber.cs abonelik koduna ve bildirimlerin devredildiği HttpHandlerDiagnosticListener.cs temel alınan uygulamaya bakın.

Daha fazla izleme mi gerekiyor?

İzleme yoluyla kullanıma sunulacak diğer yararlı bilgiler için önerileriniz varsa, bir dotnet/runtime sorunu oluşturun.