Contoh: Gunakan OpenTelemetry dengan OTLP dan Dasbor Aspire mandiri

Ini adalah salah satu dari serangkaian contoh untuk mengilustrasikan pengamatan .NET dengan OpenTelemetry.

Selain menjadi bagian standar dari .NET Aspire, Dasbor Aspire tersedia sebagai kontainer docker mandiri, yang menyediakan telemetri titik akhir OTLP dapat dikirim, dan akan memvisualisasikan log, metrik, dan jejak. Menggunakan dasbor dengan cara ini tidak memiliki dependensi pada .NET Aspire, dasbor akan memvisualisasikan telemetri dari aplikasi apa pun yang mengirimkan telemetri melalui OTLP. Ini bekerja sama baiknya untuk aplikasi yang ditulis dalam Java, GoLang, Python dll. asalkan mereka dapat mengirim telemetri mereka ke titik akhir OTLP.

Menggunakan Dasbor Aspire memiliki lebih sedikit langkah konfigurasi dan penyiapan daripada menggunakan solusi Sumber Terbuka seperti Prometheus, Grafana dan Jaeger, tetapi tidak seperti alat tersebut, Dasbor Aspire dimaksudkan sebagai alat visualisasi pengembang, dan bukan untuk pemantauan produksi.

1. Buat proyek

Buat proyek API web sederhana dengan menggunakan templat ASP.NET Core Empty di Visual Studio atau perintah .NET CLI berikut:

dotnet new web

2. Tambahkan metrik dan definisi aktivitas

Kode berikut mendefinisikan metrik baru (greetings.count) untuk berapa kali API telah dipanggil, dan sumber aktivitas baru (Otel.Example).

// 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. Buat titik akhir API

Sisipkan yang berikut ini antara builder.Build(); dan app.Run()

app.MapGet("/", SendGreeting);

Sisipkan fungsi berikut di bagian bawah file:

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. Referensi paket OpenTelemetry

Gunakan Manajer Paket NuGet atau baris perintah untuk menambahkan paket NuGet berikut:

  <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. Mengonfigurasi OpenTelemetry dengan penyedia yang benar

Sisipkan kode berikut sebelum builder.Build();:

// 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();
}

Kode ini menyiapkan OpenTelemetry dengan berbagai sumber telemetri:

• Ini menambahkan penyedia OTel ke ILogger untuk mengumpulkan catatan log.
• Ini menyiapkan metrik, mendaftarkan penyedia instrumentasi dan Meter untuk ASP.NET dan Meter kustom kami.
• Ini menyiapkan pelacakan, mendaftarkan penyedia instrumentasi dan ActivitySource kustom kami.

Kemudian mendaftarkan pengekspor OTLP menggunakan env vars untuk konfigurasinya.

6. Mengonfigurasi variabel Lingkungan OTLP

Pengekspor OTLP dapat dikonfigurasi melalui API dalam kode, tetapi lebih umum untuk mengonfigurasinya melalui variabel lingkungan. Tambahkan yang berikut ini ke AppSettings.Development.json

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

Anda dapat menambahkan variabel lingkungan tambahan untuk Pengekspor OTLP .NET atau variabel OTel umum seperti OTEL_RESOURCE_ATTRIBUTES untuk menentukan atribut sumber daya.

7. Mulai kontainer Dasbor Aspire

Gunakan docker untuk mengunduh dan menjalankan kontainer dasbor.

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

Data yang ditampilkan di dasbor bisa sensitif. Secara default, dasbor diamankan dengan autentikasi yang memerlukan token untuk masuk. Token ditampilkan dalam output yang dihasilkan saat menjalankan kontainer.

[]

Salin url yang ditampilkan, dan ganti 0.0.0.0 dengan , misalnya http://localhost:18888/login?t=123456780abcdef123456780 dan buka di browser Anda, atau Anda juga dapat menempelkan kunci setelah /login?t= ketika localhostdialog masuk ditampilkan. Token akan berubah setiap kali Anda memulai kontainer.

8. Jalankan proyek

Jalankan proyek lalu akses API dengan browser atau curl.

curl -k http://localhost:7275

Setiap kali Anda meminta halaman, halaman akan meningkatkan jumlah untuk jumlah salam yang telah dibuat.

8.1 Output log

Pernyataan pengelogan dari kode adalah output menggunakan ILogger. Secara default, Penyedia Konsol diaktifkan sehingga output diarahkan ke konsol.

Ada beberapa opsi tentang bagaimana log dapat keluar dari .NET:

• stdout dan stderr output dialihkan ke file log oleh sistem kontainer seperti Kubernetes.
• Menggunakan pustaka pengelogan yang akan diintegrasikan dengan ILogger, ini termasuk Serilog atau NLog.
• Menggunakan penyedia pengelogan untuk OTel seperti OTLP. Bagian pengelogan dalam kode dari langkah 5 menambahkan penyedia OTel.

Log ditampilkan di dasbor sebagai log terstruktur - properti apa pun yang Anda tetapkan dalam pesan log diekstrak sebagai bidang dalam catatan log.

8.2 Menampilkan metrik

Dasbor Aspire menunjukkan metrik per sumber daya (sumber daya menjadi cara OTel berbicara tentang sumber telemetri seperti proses). Saat sumber daya dipilih, dasbor akan menghitung setiap metrik yang telah dikirim ke titik akhir OTLP-nya oleh sumber daya. Daftar metrik bersifat dinamis, dan akan diperbarui saat metrik baru diterima.

Tampilan untuk metrik akan bergantung pada jenis metrik yang sedang digunakan:

• Penghitung akan ditampilkan secara langsung.
• Histogram yang melacak nilai per permintaan, seperti rentang waktu atau byte yang dikirim per permintaan, dikumpulkan ke dalam serangkaian wadah. Dasbor akan membuat grafik persentil P50, P90, dan P99. Hasil histogram dapat mencakup pengecualian, yang merupakan titik data individual bersama dengan trace/spanId untuk permintaan tersebut. Ini akan ditampilkan sebagai titik pada grafik. Memilih satu akan menavigasi ke jejak masing-masing sehingga Anda dapat melihat apa yang terjadi untuk menyebabkan nilai tersebut. Ini berguna untuk mendiagnosis outlier.
• Metrik dapat mencakup dimensi, yang merupakan pasangan kunci/nilai yang terkait dengan nilai individual. Nilai dikumpulkan per dimensi. Menggunakan menu dropdown dalam tampilan, Anda dapat memfilter hasil untuk melihat dimensi tertentu, seperti hanya GET permintaan, atau untuk rute URL tertentu di ASP.NET.

8.3 Melihat pelacakan

Tampilan pelacakan akan menampilkan daftar jejak - setiap jejak adalah serangkaian aktivitas yang berbagi traceId yang sama. Pekerjaan dilacak dengan rentang yang mewakili unit kerja. Memproses permintaan ASP.NET akan membuat rentang. Membuat permintaan HttpClient akan menjadi rentang. Dengan melacak induk rentang, hierarki rentang dapat divisualisasikan. Dengan mengumpulkan rentang dari setiap sumber daya (proses) kami melacak pekerjaan yang terjadi di serangkaian layanan. Permintaan http memiliki header yang digunakan untuk meneruskan traceId dan spanId induk ke layanan berikutnya. Setiap sumber daya perlu mengumpulkan telemetri dan mengirimkannya ke kolektor yang sama. Kemudian akan menggabungkan dan menyajikan hierarki rentang.

Dasbor akan menampilkan daftar jejak dengan informasi ringkasan. Setiap kali rentang dengan traceId baru terlihat, mereka akan mendapatkan baris dalam tabel. Tampilan mengklik akan menampilkan semua rentang dalam pelacakan.

Memilih rentang akan menampilkan detailnya termasuk properti apa pun pada rentang, seperti tag yang greeting kami tetapkan di langkah 3.