Pengamatan .NET dengan OpenTelemetry

Saat menjalankan aplikasi, Anda ingin tahu seberapa baik performa aplikasi dan mendeteksi potensi masalah sebelum menjadi lebih besar. Anda dapat melakukan ini dengan memancarkan data telemetri seperti log atau metrik dari aplikasi Anda, lalu memantau dan menganalisis data tersebut.

Apa yang dimaksud dengan pengamatan?

Pengamatan dalam konteks sistem terdistribusi adalah kemampuan untuk memantau dan menganalisis telemetri tentang status setiap komponen, untuk dapat mengamati perubahan performa, dan untuk mendiagnosis mengapa perubahan tersebut terjadi. Tidak seperti debugging, yang invasif dan dapat memengaruhi pengoperasian aplikasi, pengamatan dimaksudkan untuk transparan terhadap operasi utama dan memiliki dampak performa yang cukup kecil sehingga dapat digunakan terus menerus.

Pengamatan umumnya dilakukan menggunakan kombinasi:

• Log, yang merekam operasi individual, seperti permintaan masuk, kegagalan dalam komponen tertentu, atau pesanan yang ditempatkan.
• Metrik, yang mengukur penghitung dan pengukur seperti jumlah permintaan yang diselesaikan, permintaan aktif, widget yang telah dijual; atau histogram latensi permintaan.
• Pelacakan terdistribusi, yang melacak permintaan dan aktivitas di seluruh komponen dalam sistem terdistribusi sehingga Anda dapat melihat di mana waktu dihabiskan dan melacak kegagalan tertentu.

Bersama-sama, log, metrik, dan pelacakan terdistribusi terkadang dikenal sebagai tiga pilar pengamatan.

Setiap pilar mungkin menyertakan data telemetri dari:

• Runtime .NET, seperti pengumpul sampah atau pengkompilasi JIT.
• Pustaka, seperti dari Kestrel (server web ASP.NET) dan HttpClient.
• Telemetri khusus aplikasi yang dipancarkan oleh kode Anda.

Pendekatan pengamatan di .NET

Ada beberapa cara berbeda untuk mencapai pengamatan dalam aplikasi .NET:

• Secara eksplisit dalam kode, dengan mereferensikan dan menggunakan pustaka seperti OpenTelemetry. Jika Anda memiliki akses ke kode sumber dan dapat membangun kembali aplikasi, ini adalah mekanisme yang paling kuat dan dapat dikonfigurasi.
• Di luar proses menggunakan EventPipe. Alat seperti dotnet-monitor dapat mendengarkan log dan metrik lalu memprosesnya tanpa memengaruhi kode apa pun.
• Dengan menggunakan kait startup, rakitan dapat disuntikkan ke dalam proses yang kemudian dapat mengumpulkan instrumentasi. Contoh pendekatan ini adalah Instrumentasi Otomatis OpenTelemetry .NET.

Apa itu OpenTelemetry?

OpenTelemetry (OTel) adalah standar lintas platform, terbuka untuk mengumpulkan dan memancarkan data telemetri. OpenTelemetry meliputi:

• API untuk digunakan pustaka untuk merekam data telemetri saat kode sedang berjalan.
• API yang digunakan pengembang aplikasi untuk mengonfigurasi bagian data yang direkam apa yang akan dikirim di seluruh jaringan, tempat data tersebut akan dikirim, dan bagaimana data tersebut dapat difilter, di-buffer, diperkaya, dan diubah.
• Konvensi semantik memberikan panduan tentang penamaan dan konten data telemetri. Penting bagi aplikasi yang menghasilkan data telemetri dan alat yang menerima data untuk menyetujui jenis data yang berbeda dan jenis data apa yang berguna sehingga alat dapat memberikan analisis yang efektif.
• Antarmuka untuk pengekspor. Pengekspor adalah plugin yang memungkinkan data telemetri ditransmisikan dalam format tertentu ke backend telemetri yang berbeda.
• Protokol kawat OTLP adalah opsi protokol jaringan netral vendor untuk mengirimkan data telemetri. Beberapa alat dan vendor mendukung protokol ini selain protokol kepemilikan yang sudah ada sebelumnya yang mungkin mereka miliki.

Menggunakan OTel memungkinkan penggunaan berbagai sistem APM termasuk sistem sumber terbuka seperti Prometheus dan Grafana, Azure Monitor - Produk APM Microsoft di Azure, atau dari banyak vendor APM yang bermitra dengan OpenTelemetry.

Ada implementasi OpenTelemetry untuk sebagian besar bahasa dan platform, termasuk .NET.

Implementasi .NET dari OpenTelemetry

Implementasi .NET OpenTelemetry sedikit berbeda dari platform lain, karena .NET menyediakan API pengelogan, metrik, dan aktivitas dalam kerangka kerja. Itu berarti OTel tidak perlu menyediakan API untuk digunakan oleh penulis pustaka. Implementasi OTel .NET menggunakan API platform ini untuk instrumentasi:

• Microsoft.Extensions.Logging.ILogger<TCategoryName> untuk pengelogan
• System.Diagnostics.Metrics.Meter untuk metrik
• System.Diagnostics.ActivitySource dan System.Diagnostics.Activity untuk pelacakan terdistribusi

Ketika OTel mulai bermain adalah bahwa OTel mengumpulkan telemetri dari API tersebut dan sumber lain (melalui pustaka instrumentasi) dan kemudian mengekspornya ke sistem pemantauan performa aplikasi (APM) untuk penyimpanan dan analisis. Manfaat yang dibawa OTel sebagai standar industri adalah mekanisme umum untuk pengumpulan, skema umum dan semantik untuk data telemetri, dan API tentang bagaimana APM dapat diintegrasikan dengan OTel. Menggunakan OTel berarti bahwa aplikasi tidak perlu menggunakan API atau struktur data khusus APM; mereka bekerja melawan standar OTel. APM dapat menerapkan komponen pengekspor khusus APM atau menggunakan OTLP, yang merupakan standar kawat baru untuk mengekspor data telemetri ke sistem APM.

Paket OpenTelemetry

OpenTelemetry di .NET diimplementasikan sebagai serangkaian paket NuGet yang membentuk beberapa kategori:

• API Inti
• Instrumentasi - paket ini mengumpulkan instrumentasi dari runtime dan pustaka umum.
• Pengekspor - antarmuka ini dengan sistem APM seperti Prometheus, Jaeger, dan OTLP.

Tabel berikut ini menjelaskan paket utama.

Contoh

Topik ini dilanjutkan dengan beberapa contoh panduan untuk menggunakan OpenTelemetry di .NET:

• Contoh: Gunakan OTLP dan Dasbor Aspire mandiri
• Contoh: Menggunakan OpenTelemetry dengan Azure Monitor dan Application Insights
• Contoh: Gunakan OpenTelemetry dengan Prometheus, Grafana, dan Jaeger

OpenTelemetry di .NET Aspire

.NET Aspire adalah sekumpulan ekstensi ke .NET untuk memudahkan untuk membuat dan bekerja dengan aplikasi terdistribusi. Salah satu manfaat menggunakan .NET Aspire adalah telemetri dibangun, menggunakan pustaka OpenTelemetry untuk .NET. Templat proyek default untuk .NET Aspire berisi ServiceDefaults proyek, yang bagiannya adalah menyiapkan dan mengonfigurasi OTel. Proyek Default Layanan direferensikan dan diinisialisasi oleh setiap layanan dalam solusi .NET Aspire.

Templat proyek Default Layanan mencakup paket OTel SDK, ASP.NET, HttpClient, dan Instrumentasi Runtime, dan yang dikonfigurasi dalam Extensions.cs file. Untuk mengekspor telemetri .NET Aspire menyertakan pengekspor OTLP secara default sehingga dapat memberikan visualisasi telemetri menggunakan Dasbor Aspire.

Dasbor Aspire dirancang untuk membawa pengamatan telemetri ke siklus debug lokal, yang memungkinkan pengembang untuk tidak hanya memastikan bahwa aplikasi memproduksi telemetri, tetapi juga menggunakan telemetri tersebut untuk mendiagnosis aplikasi tersebut secara lokal. Mampu mengamati panggilan antar layanan terbukti sama bergunanya pada waktu debug seperti dalam produksi. Dasbor .NET Aspire diluncurkan secara otomatis saat Anda F5 AppHost Proyek dari Visual Studio atau dotnet run AppHost proyek.

Untuk detail selengkapnya tentang .NET Aspire lihat:

• Gambaran Umum Aspire
• Telemetri di Aspire
• Dasbor Aspire

Menggunakan kembali proyek Default Layanan tanpa .NET Aspire Orchestration

Mungkin cara term mudah untuk mengonfigurasi OTel untuk proyek ASP.NET adalah dengan menggunakan proyek Aspire Service Defaults, bahkan jika tidak menggunakan sisa .NET Aspire seperti AppHost untuk orkestrasi. Proyek Default Layanan tersedia sebagai templat proyek melalui Visual Studio atau dotnet new. Ini mengonfigurasi OTel dan menyiapkan pengekspor OTLP. Anda kemudian dapat menggunakan variabel lingkungan OTel untuk mengonfigurasi titik akhir OTLP untuk mengirim telemetri, dan menyediakan properti sumber daya untuk aplikasi.

Langkah-langkah untuk menggunakan ServiceDefaults di luar .NET Aspire adalah:

• Tambahkan proyek ServiceDefaults ke solusi menggunakan Tambahkan Proyek Baru di Visual Studio, atau gunakandotnet new aspire-servicedefaults --output ServiceDefaults
• Referensikan proyek ServiceDefaults dari aplikasi ASP.NET Anda. Di Visual Studio gunakan "Tambahkan -> Referensi Proyek" dan pilih proyek ServiceDefaults "
• Panggil fungsi penyiapan OpenTelemetry sebagai bagian dari inisialisasi pembuat aplikasi Anda.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Default Layanan dapat menyiapkan fungsionalitas tambahan berikut jika diperlukan melalui AddServiceDefaults() atau fungsi tertentu:

• Pemeriksaan kesehatan dengan /health titik akhir dan /alive
• Penemuan layanan yang akan menjadi no-op tanpa Sisa .NET Aspire
• Mengonfigurasi ketahanan untuk HttpClient yang akan mencoba kembali permintaan dalam kasus kegagalan