Pelacakan terdistribusi di pustaka System.Net

pelacakan terdistribusi adalah teknik diagnostik yang membantu teknisi melokalisasi kegagalan dan masalah performa dalam aplikasi, terutama yang didistribusikan di beberapa mesin atau proses. Teknik ini melacak permintaan melalui aplikasi dengan menghubungkan pekerjaan bersama-sama yang dilakukan oleh komponen yang berbeda dan memisahkannya dari pekerjaan lain yang mungkin dilakukan aplikasi untuk permintaan bersamaan. Misalnya, permintaan ke layanan web umum mungkin pertama kali diterima oleh load balancer dan kemudian diteruskan ke proses server web, yang kemudian membuat beberapa kueri ke database. Pelacakan terdistribusi memungkinkan teknisi untuk membedakan apakah salah satu langkah tersebut gagal dan berapa lama setiap langkah mengambil. Ini juga dapat mencatat pesan yang dihasilkan oleh setiap langkah saat dijalankan.

Sistem pelacakan di .NET dirancang untuk bekerja dengan OpenTelemetry (OTel), dan menggunakan OTel untuk mengekspor data ke sistem pemantauan. Pelacakan di .NET diimplementasikan menggunakan API System.Diagnostics, di mana unit pekerjaan diwakili oleh kelas System.Diagnostics.Activity, yang sesuai dengan rentang OTel. OpenTelemetry mendefinisikan skema penamaan standar di seluruh industri untuk rentang (aktivitas) bersama dengan atribut (tag) mereka, yang dikenal sebagai konvensi semantik . Telemetri .NET menggunakan konvensi semantik yang ada sedapat mungkin.

Instrumentasi

Untuk memancarkan jejak, pustaka System.Net berinstrumen dengan sumber ActivitySource bawaan, yang membuat objek Activity untuk melacak pekerjaan yang dilakukan. Aktivitas hanya dibuat jika ada pendengar yang berlangganan ActivitySource.

Instrumentasi bawaan berevolusi dengan versi .NET.

• Pada .NET 8 dan yang lebih lama, instrumentasi terbatas pada pembuatan aktivitas permintaan klien HTTP kosong. Ini berarti bahwa pengguna harus mengandalkan pustaka OpenTelemetry.Instrumentation.Http untuk mengisi aktivitas dengan informasi (misalnya, tag) yang diperlukan untuk menghasilkan jejak yang berguna.
• .NET 9 memperluas instrumentasi dengan memancarkan nama, status, info pengecualian, dan tag terpenting sesuai dengan konvensi semantik klien HTTP OTel pada aktivitas permintaan klien HTTP. Ini berarti bahwa pada .NET 9+, dependensi OpenTelemetry.Instrumentation.Http dapat dihilangkan, kecuali jika fitur yang lebih canggih seperti pengayaan diperlukan.
• .NET 9 juga memperkenalkan pelacakan koneksi eksperimental , menambahkan aktivitas baru di pustaka System.Net untuk mendukung mendiagnosis masalah koneksi.

Mengumpulkan jejak System.Net

Pada tingkat terendah, pengumpulan jejak didukung melalui metode AddActivityListener, yang mendaftarkan objek ActivityListener yang berisi logika yang ditentukan pengguna.

Namun, sebagai pengembang aplikasi, Anda mungkin lebih suka mengandalkan ekosistem kaya yang dibangun berdasarkan fitur yang disediakan oleh OpenTelemetry .NET SDK untuk mengumpulkan, mengekspor, dan memantau jejak.

• Untuk mendapatkan pemahaman dasar tentang pengumpulan jejak dengan OTel, lihat panduan kami tentang mengumpulkan jejak menggunakan OpenTelemetry.
• Untuk pengumpulan dan pemantauan jejak waktu produksi, Anda dapat menggunakan OpenTelemetry dengan Prometheus, Grafana, dan Jaeger atau dengan Azure Monitor dan Application Insights. Namun, alat-alat ini cukup kompleks dan mungkin tidak nyaman digunakan pada waktu pengembangan.
• Untuk pengumpulan dan pemantauan jejak waktu pengembangan, sebaiknya gunakan .NET Aspire yang menyediakan cara sederhana tetapi dapat diperluas untuk memulai pelacakan terdistribusi dalam aplikasi Anda dan untuk mendiagnosis masalah secara lokal.
• Anda juga dapat menggunakan kembali proyek Pengaturan Bawaan Layanan Aspire tanpa orkestrasi Aspire. Ini adalah cara yang berguna untuk memperkenalkan dan mengonfigurasi pelacakan dan metrik OpenTelemetry dalam proyek ASP.NET Anda.

Mengumpulkan pelacakan dengan .NET Aspire

Cara sederhana untuk mengumpulkan jejak dan metrik dalam aplikasi ASP.NET adalah dengan menggunakan .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 sudah terintegrasi, yang menggunakan pustaka OpenTelemetry untuk .NET.

Templat proyek default untuk .NET Aspire berisi proyek ServiceDefaults. Setiap layanan dalam solusi .NET Aspire memiliki referensi ke proyek Standar Layanan. Layanan menggunakannya untuk menyiapkan dan mengonfigurasi OTel.

Templat proyek Bawaan Layanan mencakup paket OTel SDK, ASP.NET, HttpClient, dan Instrumentasi Runtime. Komponen instrumentasi ini dikonfigurasi dalam file Extensions.cs. Untuk mendukung visualisasi telemetri di Dasbor Aspire, proyek Default Layanan juga menyertakan pengekspor OTLP secara default.

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

Untuk informasi selengkapnya tentang .NET Aspire, lihat:

• Gambaran Umum Aspire
• Telemetri pada Aspire
• Dasbor Aspire

Gunakan kembali proyek Pengaturan Default Layanan tanpa .NET Aspire Orchestration

Proyek Aspire Service Defaults menyediakan cara mudah untuk mengonfigurasi OTel untuk proyek ASP.NET, bahkan jika tidak menggunakan .NET Aspire lainnya seperti AppHost untuk orkestrasi. Proyek Layanan Default 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:

1. Tambahkan proyek ServiceDefaults ke solusi menggunakan Tambahkan Proyek Baru di Visual Studio, atau gunakan dotnet new:

   dotnet new aspire-servicedefaults --output ServiceDefaults
   

2. Referensikan ServiceDefaults project dari aplikasi ASP.NET Anda. Di Visual Studio, pilih Tambah>Referensi Proyek dan pilih proyek ServiceDefaults

3. Panggil fungsi penyiapan OpenTelemetry ConfigureOpenTelemetry() sebagai bagian dari inisialisasi pembuat aplikasi Anda.

   var builder = WebApplication.CreateBuilder(args)
   builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
   var app = builder.Build();
   app.MapGet("/", () => "Hello World!");
   app.Run();
   

Untuk panduan lengkap, lihat Contoh : Menggunakan OpenTelemetry dengan OTLP dan Dasbor Aspire mandiri.

Pelacakan koneksi eksperimental

Saat memecahkan masalah HttpClient atau hambatan, mungkin penting untuk melihat di mana waktu dihabiskan saat mengirim permintaan HTTP. Seringkali, masalah terjadi selama pembentukan koneksi HTTP, yang biasanya terbagi menjadi pencarian DNS, koneksi TCP, dan jabat tangan TLS.

.NET 9 memperkenalkan pelacakan koneksi yang bersifat eksperimental, menambahkan rentang berlabel HTTP connection setup dengan tiga rentang anak yang mewakili fase DNS, TCP, dan TLS dalam proses pembentukan koneksi. Bagian HTTP dari pelacakan koneksi diimplementasikan dalam SocketsHttpHandler, yang berarti bahwa model aktivitas harus menghormati perilaku pengumpulan koneksi yang mendasarinya.

.NET 9 memperkenalkan rentang berikut untuk memungkinkan pengumpulan informasi koneksi terperinci:

Rentang ini terlalu verbose untuk digunakan 24x7 dalam skenario produksi dengan beban kerja tinggi - mereka berisik dan tingkat instrumentasi ini biasanya tidak diperlukan. Namun, jika Anda mencoba mendiagnosis masalah koneksi atau mendapatkan pemahaman yang lebih mendalam tentang bagaimana latensi jaringan dan koneksi memengaruhi layanan Anda, maka mereka memberikan wawasan yang sulit dikumpulkan dengan cara lain.

Saat Experimental.System.Net.Http.Connections ActivitySource diaktifkan, rentang HTTP client request berisi tautan ke rentang HTTP connection_setup yang sesuai dengan koneksi yang melayani permintaan. Karena koneksi HTTP dapat berumur panjang, ini dapat mengakibatkan banyak tautan ke rentang koneksi dari setiap aktivitas permintaan. Beberapa alat pemantauan kinerja APM secara agresif menelusuri tautan antara rentang penelusuran untuk membangun pandangan mereka, sehingga penyertaan rentang ini dapat menyebabkan masalah ketika alat tersebut tidak dirancang untuk memperhitungkan sejumlah besar tautan.

Diagram berikut mengilustrasikan perilaku rentang dan hubungannya:

Panduan: Menggunakan pelacakan koneksi eksperimental di .NET 9

Panduan ini menggunakan Aplikasi Aspire Starter .NET 9 untuk menunjukkan pelacakan koneksi, tetapi seharusnya mudah untuk mengaturnya dengan alat pemantauan lain juga. Langkah utamanya adalah mengaktifkan ActivitySources.

1. Buat Aplikasi Starter .NET Aspire 9 dengan menggunakan dotnet new.

   dotnet new aspire-starter-9 --output ConnectionTracingDemo
   

   Atau di Visual Studio:

   

2. Buka Extensions.cs dalam proyek ServiceDefaults, dan edit metode ConfigureOpenTelemetry untuk menambahkan ActivitySources dalam panggilan balik konfigurasi pelacakan agar terhubung:

   .WithTracing(tracing =>
   {
       tracing.AddAspNetCoreInstrumentation()
           // Instead of using .AddHttpClientInstrumentation()
           // .NET 9 allows to add the ActivitySources directly.
           .AddSource("System.Net.Http")
           // Add the experimental connection tracking ActivitySources using a wildcard.
           .AddSource("Experimental.System.Net.*");
   });
   

3. Mulai solusinya. Ini akan membuka Dasbor Aspire .NET.

4. Buka halaman Cuaca di aplikasi webfrontend untuk membuat permintaan HttpClient menuju apiservice.

5. Kembali ke Dasbor dan navigasi ke halaman Jejak . Buka jejak webfrontend: GET /weather.

   Dasbor Aspire

Ketika permintaan HTTP dibuat dengan instrumentasi koneksi diaktifkan, Anda akan melihat perubahan berikut pada rentang permintaan klien:

• Jika koneksi perlu dibuat, atau jika aplikasi menunggu koneksi dari kumpulan koneksi, rentang HTTP wait_for_connection tambahan ditampilkan, yang mewakili penundaan untuk menunggu koneksi dibuat. Ini membantu memahami penundaan antara permintaan HttpClient yang dibuat dalam kode, dan ketika pemrosesan permintaan benar-benar dimulai. Pada gambar sebelumnya:
  • Rentang yang dipilih merupakan permintaan HttpClient.
  • Rentang di bawah ini mewakili waktu yang dihabiskan permintaan menunggu koneksi dibuat.
  • Rentang terakhir berwarna kuning adalah dari tujuan yang memproses permintaan.
• Rentang HttpClient akan memiliki tautan ke rentang HTTP connection_setup, yang mewakili aktivitas untuk membuat koneksi HTTP yang digunakan oleh permintaan.

Dasbor Aspire

Seperti disebutkan sebelumnya, rentang HTTP connection_setup adalah rentang terpisah dengan TraceIdsendiri , karena masa pakainya independen dari setiap permintaan klien individu. Rentang ini biasanya memiliki subrentang DNS lookup, (TCP) socket connect, dan TLS client handshake.

Pengayaan

Dalam beberapa kasus, perlu untuk menambah fungsionalitas pelacakan System.Net yang sudah ada. Biasanya ini berarti menyuntikkan tag/atribut tambahan ke aktivitas bawaan. Ini disebut pengayaan.

API pengayaan di pustaka instrumentasi OpenTelemetry

Untuk menambahkan tag/atribut tambahan ke aktivitas permintaan klien HTTP, pendekatan paling sederhana adalah menggunakan API pengayaan HttpClient pustaka instrumentasi OpenTelemetry HttpClient dan HttpWebRequest. Ini mengharuskan mengambil dependensi pada paket OpenTelemetry.Instrumentation.Http.

Pengayaan manual

Dimungkinkan untuk menerapkan pengayaan aktivitas HTTP client request secara manual. Untuk ini, Anda perlu mengakses Activity.Current dalam kode yang berjalan dalam cakupan aktivitas permintaan, sebelum aktivitas selesai. Ini dapat dilakukan dengan menerapkan IObserver<DiagnosticListener> dan berlangganan ke AllListeners untuk mendapatkan panggilan balik saat aktivitas jaringan terjadi. Sebenarnya, inilah cara pustaka instrumentasi OpenTelemetry HttpClient dan HttpWebRequest diimplementasikan. Untuk contoh kode, lihat kode langganan di DiagnosticSourceSubscriber.cs dan implementasi yang mendasar di HttpHandlerDiagnosticListener.cs tempat pemberitahuan didelegasikan.

Perlu lebih banyak pelacakan?

Jika Anda memiliki saran untuk informasi berguna lainnya yang dapat diekspos melalui pelacakan, laporkan masalah pada dotnet/runtime .