Örnek: OTLP ve tek başına Aspire Panosu ile OpenTelemetry kullanma

Bu, OpenTelemetry ile .NET gözlemlenebilirliğini gösteren bir dizi örnektir.

.NET Aspire'in standart bir parçası olmasının yanı sıra, Aspire Panosu'na otLP uç noktası telemetrisi gönderilebilen tek başına bir docker kapsayıcısı olarak da kullanılabilir ve günlükleri, ölçümleri ve izlemeleri görselleştirir. Panoyu bu şekilde kullanmak .NET Aspire bağımlılığına sahip değildir, OTLP aracılığıyla telemetri gönderen herhangi bir uygulamadan gelen telemetri verilerini görselleştirir. Java, GoLang, Python vb. ile yazılmış uygulamalar için de aynı derecede iyi çalışır. telemetrilerini bir OTLP uç noktasına gönderebileceklerini varsayın.

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çların aksine 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

ve arasına builder.Build(); aşağıdakileri ekleyin app.Run()

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!";
}

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>

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çümler ayarlayıp ölçüm sağlayıcılarını ve ölçümlerini ASP.NET ve özel Ölçümümüz için kaydeder.
• İzlemeyi, izleme sağlayıcılarını ve özel ActivitySource'umuzu kaydeder.

Ardından, yapılandırması için env değişkenlerini kullanarak OTLP verme işlemini kaydeder.

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

OTLP dışarı aktarma koddaki 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.

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

Pano kapsayıcısını indirmek ve çalıştırmak için docker kullanı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, panonun güvenliği oturum açmak için bir belirteç gerektiren kimlik doğrulamasıyla sağlanır. Belirteç, kapsayıcı çalıştırılırken elde edilen çıktıda görüntülenir.

[]

Gösterilen URL'yi kopyalayın ve yerine 0.0.0.0 localhosthttp://localhost:18888/login?t=123456780abcdef123456780 öğesini yazın ve tarayıcınızda açın ya da oturum açma iletişim kutusu gösterildikten sonra /login?t= anahtarı 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ı artacaktır.

8.1 Günlük çıkışı

Koddaki günlük deyimleri kullanılarak ILoggerçıkıştır. 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:

• stdoutve stderr çıkışı Kubernetes gibi kapsayıcı sistemleri tarafından günlük dosyalarına yönlendirilir.
• Bunlar, ILogger ile tümleştirilecek günlük kitaplıklarını kullanarak Serilog veya NLog içerir.
• OTLP gibi OTel için günlük sağlayıcılarını kullanma. 5. adımdaki koddaki günlük 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 (bir kaynak, işlem gibi telemetri kaynakları hakkında konuşmanın OTel yoludur). 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ılan ö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. Pano P50, P90 ve P99 yüzde birlik değerlerinin grafiğini oluşturur. Histogram sonuçları, bu isteğin trace/spanId değeriyle birlikte tek tek veri noktaları olan örnekleri içerebilir. Bunlar grafikte nokta olarak gösterilir. Birini seçtiğinizde ilgili izlemeye gider ve bu değere neyin neden olduğunu 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ı yalnızca istekler gibi GET belirli boyutlara veya ASP.NET belirli bir URL yolu için olan boyutlara bakmak üzere filtreleyebilirsiniz.

8.3 İzlemeyi görüntüleme

İzleme görünümünde izlemelerin listesi gösterilir. Her izleme aynı traceId değerini paylaşan bir etkinlik 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 yayılma alanı olacaktır. Span'ın üst öğesi izlenerek, bir span hiyerarşisi görselleştirilebilir. Her kaynaktan (işlem) yayılma alanları toplayarak, bir dizi hizmette gerçekleşen işleri izleriz. Http isteklerinde traceId ve üst spanId değerlerini sonraki hizmete geçirmek için kullanılan bir üst bilgi bulunur. Her kaynağın telemetriyi toplaması ve aynı toplayıcıya göndermesi gerekir. Daha sonra bir aralık hiyerarşisi toplar ve sunar.

Panoda özet bilgileri içeren izlemelerin listesi gösterilir. Yeni traceId içeren span'lar her görüldüğünde tabloda bir satır alır. Görünüme tıklanırken izlemedeki tüm yayılma alanları gösterilir.

Bir yayılma alanı seçildiğinde, 3. adımda ayarlamış olduğumuz etiket gibi span'daki tüm özellikler de dahil olmak üzere greeting ayrıntılarını gösterir.