Contoh: Gunakan OpenTelemetry dengan OTLP dan Dasbor mandiri Aspire

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

Selain menjadi bagian standar dari Aspire, dasbor Aspire tersedia sebagai kontainer Docker mandiri, yang menyediakan titik akhir OTLP yang dapat digunakan untuk mengirim telemetri. Dasbor memvisualisasikan log, metrik, dan jejak. Penggunaan dasbor dengan cara ini tidak memiliki dependensi pada Aspire, dan memvisualisasikan data telemetri dari aplikasi apa pun yang mengirimkannya melalui OTLP. Ini bekerja sama baiknya untuk aplikasi yang ditulis dalam Java, GoLang, atau Python asalkan mereka dapat mengirim telemetri mereka ke titik akhir OTLP.

Aspire Menggunakan Dasbor memiliki lebih sedikit langkah konfigurasi dan penyiapan daripada menggunakan solusi Sumber Terbuka seperti Prometheus, Grafana, dan Jaeger. Tetapi tidak seperti alat-alat tersebut Aspire , Dasbor 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 kode berikut 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. Rujuklah 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 alat ukur dan Meter untuk ASP.NET serta meter kami yang kustom.
• Ini mengatur pelacakan, mendaftarkan penyedia instrumentasi, dan ActivitySource khusus 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 Aspire kontainer Dashboard

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 localhost, misalnya, http://localhost:18888/login?t=123456780abcdef123456780, dan buka di browser Anda. Atau Anda juga dapat menempelkan kunci setelah /login?t= ketika dialog login ditampilkan. Token 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, jumlah salam yang telah dibuat akan bertambah.

8.1 Output log

Pernyataan logging dari kode dioutput 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 terintegrasi dengan ILogger. Pustaka ini termasuk Serilog dan 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 menampilkan metrik berdasarkan per sumber daya (dalam hal ini, 'sumber daya' adalah istilah yang digunakan oleh OTel untuk merujuk pada sumber-sumber telemetri seperti proses). Saat sumber daya dipilih, dasbor menghitung setiap metrik yang telah dikirim ke titik akhir OTLP-nya oleh sumber daya. Daftar metrik bersifat dinamis, dan diperbarui saat metrik baru diterima.

Tampilan untuk metrik tergantung pada jenis metrik yang sedang digunakan:

• Penghitung ditampilkan secara langsung.
• Histogram yang melacak nilai per permintaan, seperti rentang waktu atau byte yang dikirim per permintaan, dikumpulkan ke dalam serangkaian wadah. Dasbor membuat grafik persentil P50, P90, dan P99. Hasil histogram dapat mencakup contoh, yang merupakan titik data individual bersama dengan trace/spanId untuk permintaan tersebut. Ini ditampilkan sebagai titik-titik pada grafik. Memilih satu akan menavigasi ke jejak yang sesuai sehingga Anda dapat melihat apa yang terjadi yang 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. Dengan menggunakan menu dropdown pada tampilan, Anda dapat memfilter hasil untuk melihat dimensi tertentu, seperti hanya permintaan GET, atau untuk rute URL tertentu di ASP.NET.

8.3 Melihat pelacakan

Tampilan pelacakan memperlihatkan daftar jejak. Setiap jejak adalah serangkaian aktivitas yang memiliki traceId yang sama. Pekerjaan dilacak dengan rentang, yang mewakili unit kerja. Memproses permintaan ASP.NET membuat rentang. Mengajukan permintaan HttpClient merupakan operasi yang mencakup waktu. Dengan melacak induk rentang, hierarki rentang dapat divisualisasikan. Dengan mengumpulkan rentang dari setiap sumber daya (proses), Anda dapat 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. Sistem kemudian akan menggabungkan dan menyajikan hierarki rentang.

Dasbor memperlihatkan daftar jejak dengan informasi ringkasan. Setiap kali rentang dengan traceId baru terlihat, mereka mendapatkan baris dalam tabel. Mengklik "lihat" memperlihatkan semua rentang dalam pelacakan.

Memilih rentang memperlihatkan detailnya termasuk properti apa pun pada rentang, seperti greeting tag yang Anda tetapkan di langkah 3.