Örnek: OTLP ve bağımsız Aspire Panosu ile OpenTelemetry kullanma

Bu makale, OpenTelemetry ile .NET gözlemlenebilirliğini gösteren bir dizi örnekten biridir.

Aspire'in standart bir parçası olmasının yanı sıra, Aspire Panosu telemetrinin gönderilebileceği bir OTLP uç noktası sağlayan tek başına bir Docker kapsayıcısı olarak da kullanılabilir. Pano günlükleri, ölçümleri ve izlemeleri görselleştirir. Panoyu bu şekilde kullanmak Aspire'a bağımlı değildir ve OTLP aracılığıyla telemetri gönderen herhangi bir uygulamadan gelen telemetri verilerini görselleştirir. Telemetrilerini bir OTLP uç noktasına gönderebiliyor olmaları koşuluyla Java, GoLang veya Python ile yazılmış uygulamalar için de aynı derecede iyi çalışır.

Aspire Panosu'nu kullanmak Prometheus, Grafana ve Jaeger gibi Açık Kaynak çözümleri kullanmaktan daha az yapılandırma ve kurulum adımına sahiptir. Ancak bu araçlardan farklı olarak Aspire Panosu, üretim izleme için değil geliştirici görselleştirme aracı olarak tasarlanmıştır.

1. Projeyi oluşturma

Visual Studio'da ASP.NET Core Empty şablonunu veya aşağıdaki .NET CLI komutunu kullanarak basit bir web API'si projesi oluşturun:

dotnet new web

2. Ölçüm ve etkinlik tanımları ekleme

Aşağıdaki kod, API'nin çağrılma sayısı için yeni bir ölçüm (greetings.count) ve yeni bir etkinlik kaynağı (Otel.Example) tanımlar.

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. API uç noktası oluşturma

"Aşağıdaki kodu builder.Build(); ve app.Run() arasına ekleyin"

app.MapGet("/", SendGreeting);

Dosyanın en altına aşağıdaki işlevi ekleyin:

async Task<string> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

Not

Uç nokta tanımı OpenTelemetry'ye özgü bir şey kullanmaz. Gözlemlenebilirlik için .NET API'lerini kullanır.

4. OpenTelemetry paketlerine başvurun

Aşağıdaki NuGet paketlerini eklemek için NuGet Paket Yöneticisi veya komut satırını kullanın:

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

Not

OTel API'leri sürekli geliştikçe en son sürümleri kullanın.

5. OpenTelemetry'yi doğru sağlayıcılarla yapılandırın

Önce aşağıdaki kodu builder.Build();ekleyin:

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

Bu kod, farklı telemetri kaynaklarıyla OpenTelemetry'yi ayarlar:

• Günlük kayıtlarını toplamak için ILogger'a bir OTel sağlayıcısı ekler.
• Ölçüm sağlayıcılarını ve Metrikleri ASP.NET ve özel Ölçüm Cihazımız için ayarlayıp kaydeder.
• İzlemeyi kurar, enstrümantasyon sağlayıcılarını kaydeder ve özel ActivitySource'umuzu oluşturur.

Ardından, yapılandırması için çevre değişkenlerini kullanarak OTLP dışa aktarıcısını kaydeder.

6. OTLP Ortamı değişkenlerini yapılandırma

OTLP dışarı aktarma kodundaki API'ler aracılığıyla yapılandırılabilir, ancak ortam değişkenleri aracılığıyla yapılandırmak daha yaygındır. aşağıdakileri AppSettings.Development.json ekleyin

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

.NET OTLP Dışarı Aktarma için ek ortam değişkenleri veya kaynak özniteliklerini tanımlamak için gibi OTEL_RESOURCE_ATTRIBUTES yaygın OTel değişkenleri ekleyebilirsiniz.

Not

Yaygın bir gotcha, AppSettings.json ve AppSettings.Development.jsonkarıştırmaktır. İkinci seçenek mevcutsa, Visual Studio'dan F5'i kullandığınızda kullanılır ve AppSettings.json ayarları yoksayılır.

7. Aspire Panosu kapsayıcısını başlatın

docker kullanarak pano kapsayıcısını indirin ve çalıştırın.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

Panoda görüntülenen veriler hassas olabilir. Varsayılan olarak, kontrol panelinin güvenliği oturum açmak için bir belirteç gerektiren kimlik doğrulama ile sağlanır. Belirteç, kapsayıcı çalıştırılırken elde edilen çıktıda görüntülenir.

Aspire Panosu

Gösterilen URL'yi kopyalayın ve yerine 0.0.0.0localhostörneğin , http://localhost:18888/login?t=123456780abcdef123456780yazın ve bunu tarayıcınızda açın. İsterseniz, oturum açma iletişim kutusu gösterildiğinde /login?t= anahtarı da yapıştırabilirsiniz. Kapsayıcıyı her başlattığınızda belirteç değişir.

8. Projeyi çalıştırma

Projeyi çalıştırın ve ardından tarayıcı veya curl ile API'ye erişin.

curl -k http://localhost:7275

Sayfayı her istediğinizde, yapılan karşılama sayısının sayısını artırır.

8.1 Kayıt çıkışı

Koddaki günlük ifadeleri kullanılarak ILogger çıkışı alınıyor. Varsayılan olarak, çıktının konsola yönlendirilmesi için Konsol Sağlayıcısı etkinleştirilir.

Günlüklerin .NET'ten nasıl çıkarılacağına ilişkin birkaç seçenek vardır:

• stdout ve stderr çıkışı Kubernetes gibi kapsayıcı sistemleri tarafından günlük dosyalarına yönlendirilir.
• ILogger ile entegre olan günlükleme kütüphanelerini kullanma. Bu kitaplıklar Serilog ve NLog'dur.
• OTel için OTLP gibi günlük sağlayıcılar kullanma. Kodun 5. adımındaki loglama bölümü OTel sağlayıcısını ekler.

Günlükler panoda yapılandırılmış günlükler olarak gösterilir. Günlük iletisinde ayarladığınız tüm özellikler günlük kaydında alan olarak ayıklanır.

8.2 Ölçümleri görüntüleme

Aspire panosu, ölçümleri kaynak bazında gösterir (burada kaynak, işlemler gibi telemetri kaynaklarını ifade eden OTel terimidir). Bir kaynak seçildiğinde pano, kaynak tarafından OTLP uç noktasına gönderilen her ölçümü numaralandırır. Ölçüm listesi dinamiktir ve yeni ölçümler alındıkçe güncelleştirilir.

Ölçümlerin görünümü, kullanılmakta olan ölçümün türüne bağlıdır:

• Sayaçlar doğrudan gösterilir.
• zaman aralığı veya istek başına gönderilen baytlar gibi istek başına bir değeri izleyen histogramlar bir dizi demet halinde toplanır. Panoda P50, P90 ve P99 yüzdebirlik dilimleri çizilmektedir. Histogram sonuçları, bu isteğe ait trace/spanId ile birlikte tek tek veri noktalarını içeren örnekler de içerebilir. Bunlar grafikte nokta olarak gösterilir. Birini seçtiğinizde ilgili izlemenin içine gider, böylece bu değerin oluşma nedenini görebilirsiniz. Bu, aykırı değerleri tanılamak için yararlıdır.
• Ölçümler, tek tek değerlerle ilişkili anahtar/değer çiftleri olan boyutları içerebilir. Değerler boyut başına toplanır. Görünümdeki açılan menüleri kullanarak sonuçları filtreleyebilir ve yalnızca GET istekler gibi belirli boyutlara veya ASP.NET'deki belirli bir URL yolunun boyutlarına bakabilirsiniz.

8.3 İzlemeyi görüntüleme

İzleme görünümünde izlerin listesi gösterilir. Her izleme, aynı izleme kimlik numarasını (traceId) paylaşan bir aktivite kümesidir. Çalışma, bir çalışma birimini temsil eden aralıklarla izlenir. bir ASP.NET isteğinin işlenmesi bir yayılma alanı oluşturur. HttpClient isteği yapmak bir zaman dilimidir. Span'in ebeveyni izlenerek, bir span hiyerarşisi görselleştirilebilir. Her kaynaktan (işlem) yayılma alanları toplayarak, bir dizi hizmette gerçekleşen çalışmaları izleyebilirsiniz. HTTP isteklerinin başlık kısmında, traceId ve ana spanId'yi bir sonraki hizmete iletmek için kullanılan bilgiler bulunur. Her kaynağın telemetriyi toplaması ve aynı toplayıcıya göndermesi gerekir. Daha sonra bir aralık hiyerarşisi toplar ve sunar.

Pano, özet bilgileri içeren izlemelerin listesini gösterir. Yeni traceId içeren span'lar her görüldüğünde tabloda bir satır alır. Görünüme tıklamak, izdeki tüm aralıkları gösterir.

Bir span seçildiğinde, greeting etiketini 3. adımda ayarladığınız gibi span'daki tüm özellikler de dahil olmak üzere detaylarını gösterir.