Observabilitas .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 penghitungan dan pengukur seperti jumlah permintaan yang diselesaikan, jumlah permintaan aktif, jumlah 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.
  • Library, seperti dari Kestrel (server web ASP.NET) dan HttpClient.
  • Telemetri khusus aplikasi yang dihasilkan oleh kode Anda sendiri.

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 hook startup, rakitan dapat disuntikkan ke dalam proses untuk mengumpulkan data instrumentasi. Contoh pendekatan ini adalah OpenTelemetry .NET Instrumentasi Otomatis.

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 yang sudah ada 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:

Arsitektur OTel .NET

Peran OTel adalah mengumpulkan telemetri dari API tersebut dan sumber lain (melalui pustaka instrumentasi) dan kemudian mengekspornya ke sistem pemantauan kinerja 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 ini berinteraksi dengan sistem APM seperti Prometheus, Jaeger, dan OTLP.

Tabel berikut ini menjelaskan paket utama.

Nama Paket Deskripsi
OpenTelemetry Pustaka utama yang menyediakan fungsionalitas OTEL inti
OpenTelemetry.Instrumentation.AspNetCore Instrumentasi untuk ASP.NET Core dan Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient Instrumentasi untuk Klien gRPC untuk pemantauan panggilan gRPC yang keluar
OpenTelemetry.Instrumentation.Http Instrumentasi untuk melacak panggilan HTTP keluar pada HttpClient dan HttpWebRequest
OpenTelemetry.Instrumentation.SqlClient Instrumentasi SqlClient digunakan untuk melacak operasi basis data
OpenTelemetry.Exporter.Console Pengekspor untuk konsol, umumnya digunakan untuk mendiagnosis telemetri apa yang sedang diekspor
OpenTelemetry.Exporter.OpenTelemetryProtocol Pengekspor menggunakan protokol OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore Pengekspor untuk Prometheus diimplementasikan menggunakan endpoint ASP.NET Core
OpenTelemetry.Exporter.Zipkin Pengekspor untuk pelacakan Zipkin

Contoh

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

OpenTelemetry di Aspire

Aspire adalah sekumpulan ekstensi untuk .NET agar mudah dibuat dan bekerja dengan aplikasi terdistribusi. Salah satu manfaat menggunakan Aspire adalah telah terintegrasinya telemetri dengan menggunakan pustaka OpenTelemetry untuk .NET. Templat proyek default untuk Aspire berisi ServiceDefaults proyek, yang bagiannya adalah menyiapkan dan mengonfigurasi OTel. Proyek Bawaan Layanan dirujuk dan diinisialisasi oleh setiap layanan dalam solusi Aspire.

Templat proyek Standar Layanan mencakup paket OTel SDK, ASP.NET, HttpClient, dan Instrumentasi Runtime, dan dikonfigurasi dalam berkas Extensions.cs. Untuk mengekspor telemetri, Aspire sertakan pengekspor OTLP secara default sehingga dapat menyediakan visualisasi telemetri menggunakan Aspire Dasbor.

Aspire Dasbor 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 Aspire diluncurkan secara otomatis saat Anda menekan F5 pada AppHost project dari Visual Studio atau dotnet runAppHost project.

Aspire Dashboard

Untuk detail selengkapnya tentang Aspire lihat:

Menggunakan kembali proyek Default Layanan tanpa Aspire Orkestrasi

Mungkin cara termudah untuk mengonfigurasi OTel pada proyek ASP.NET adalah dengan menggunakan proyek Aspire Service Defaults, bahkan jika tidak memanfaatkan bagian lain dari Aspire, seperti AppHost untuk keperluan orkestrasi. Proyek Service Defaults 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 Aspire adalah:

  • Tambahkan proyek ServiceDefaults ke solusi menggunakan Tambahkan Proyek Baru di Visual Studio, atau gunakan dotnet 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 pengaturan 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();

Pengaturan Bawaan Layanan dapat menyiapkan fungsionalitas tambahan berikut, jika diperlukan, melalui AddServiceDefaults() atau fungsi spesifik.

  • Pemeriksaan kesehatan dengan /health dan /alive endpoint.
  • Penemuan layanan, yang akan menjadi operasi yang tidak berpengaruh tanpa bagian lain dari Aspire.
  • Mengonfigurasi ketahanan untuk HttpClient, yang mengulangi permintaan dalam kasus kegagalan.
  • Last updated on