Saluran telemetri di Application Insights

  • Artikel

Saluran telemetri adalah bagian integral dari SDK Application Insights. Mereka mengelola buffering dan transmisi telemetri ke layanan Application Insights. SDK versi .NET dan .NET Core memiliki dua saluran telemetri bawaan: InMemoryChannel dan ServerTelemetryChannel. Artikel ini menjelaskan setiap saluran dan menunjukkan cara menyesuaikan perilaku saluran.

Catatan

Dokumentasi berikut bergantung pada API klasik Application Insights. Rencana jangka panjang untuk Application Insights adalah mengumpulkan data menggunakan OpenTelemetry. Untuk informasi selengkapnya, lihat Mengaktifkan Azure Monitor OpenTelemetry untuk aplikasi .NET, Node.js, Python, dan Java.

Apa itu saluran telemetri?

Saluran telemetri bertanggung jawab untuk buffering item telemetri dan mengirimkannya ke layanan Application Insights, di mana mereka disimpan untuk kueri dan analisis. Saluran telemetri adalah kelas apa pun yang mengimplementasikan Microsoft.ApplicationInsights.ITelemetryChannel antarmuka.

Metode Send(ITelemetry item) saluran telemetri dipanggil setelah semua inisialisasi telemetri dan prosesor telemetri dipanggil. Jadi, item apa pun yang dihilangkan oleh prosesor telemetri tidak akan mencapai saluran. Metode ini Send() biasanya tidak mengirim item ke back end secara instan. Biasanya, ia buffer mereka dalam memori dan mengirimkannya dalam batch untuk transmisi yang efisien.

Aliran Metrik Langsung juga memiliki saluran khusus yang mendukung streaming langsung telemetri. Saluran ini independen dari saluran telemetri reguler, dan dokumen ini tidak berlaku untuk saluran tersebut.

Saluran telemetri bawaan

SDK Application Insights .NET dan .NET Core dikirmkan dengan dua saluran bawaan:

  • InMemoryChannel: Saluran ringan yang buffer item dalam memori sampai dikirim. Item di-buffer dalam memori dan dibersihkan setiap 30 detik sekali, atau setiap kali 500 item di-buffer. Saluran ini menawarkan jaminan keandalan minimal karena tidak mencoba lagi mengirim telemetri setelah kegagalan. Saluran ini juga tidak menyimpan item pada disk. Jadi setiap item yang tidak terduga hilang secara permanen setelah aplikasi dimatikan, baik itu anggun atau tidak. Saluran ini mengimplementasikan metode Flush() yang dapat digunakan untuk mematikan paksa item telemetri dalam memori secara sinkron. Saluran ini sangat cocok untuk aplikasi jangka pendek di mana membersihkan sinkron sangat ideal.

    Saluran ini adalah bagian dari paket Microsoft.ApplicationInsights NuGet yang lebih besar dan merupakan saluran default yang digunakan SDK ketika tidak ada yang lain yang dikonfigurasi.

  • ServerTelemetryChannel: Saluran yang lebih canggih yang memiliki kebijakan mencoba kembali dan kemampuan untuk menyimpan data di disk lokal. Saluran ini mencoba kembali mengirim telemetri jika terjadi kesalahan sementara. Saluran ini juga menggunakan pembersihan disk lokal untuk menjaga item pada disk selama pemadaman jaringan atau volume telemetri tinggi. Karena mekanisme coba lagi dan penyimpanan disk lokal ini, saluran ini dianggap lebih dapat diandalkan. Kami merekomendasikannya untuk semua skenario produksi. Saluran ini adalah default untuk aplikasi ASP.NET dan ASP.NET Core yang dikonfigurasi sesuai dengan dokumentasi resmi. Saluran ini dioptimalkan untuk skenario server dengan proses yang berjalan lama. Metode Flush() yang diterapkan oleh saluran ini tidak sinkron.

    Saluran ini dikirimkan sebagai paket NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel dan diperoleh secara otomatis saat Anda menggunakan paket NuGet Microsoft.ApplicationInsights.Web atau Microsoft.ApplicationInsights.AspNetCore.

Mengonfigurasi saluran telemetri

Anda mengonfigurasi saluran telemetri dengan mengaturnya ke konfigurasi telemetri aktif. Untuk aplikasi ASP.NET, konfigurasi melibatkan pengaturan instans saluran telemetri ke TelemetryConfiguration.Active atau dengan memodifikasi ApplicationInsights.config. Untuk aplikasi ASP.NET Core, konfigurasi melibatkan penambahan saluran ke kontainer injeksi dependensi.

Bagian berikut menunjukkan contoh mengonfigurasi pengaturan StorageFolder untuk saluran dalam berbagai jenis aplikasi. StorageFolder hanyalah salah satu pengaturan yang dapat dikonfigurasi. Untuk daftar lengkap pengaturan konfigurasi, lihat bagian Pengaturan yang dapat dikonfigurasi di saluran nanti di artikel ini.

Konfigurasi dengan menggunakan ApplicationInsights.config untuk aplikasi ASP.NET

Bagian berikut dari ApplicationInsights.config memperlihatkan saluran ServerTelemetryChannel yang dikonfigurasi dengan StorageFolder diatur ke lokasi kustom:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity  -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

Konfigurasi dalam kode untuk aplikasi ASP.NET

Kode berikut menyiapkan ServerTelemetryChannel instans dengan StorageFolder diatur ke lokasi kustom. Tambahkan kode ini di awal aplikasi, biasanya dalam Application_Start() metode dalam Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
    serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Konfigurasi dalam kode untuk aplikasi ASP.NET

Ubah metode ConfigureServices kelas Startup.cs seperti yang ditunjukkan di sini:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Penting

Mengonfigurasi saluran dengan menggunakan TelemetryConfiguration.Active tidak didukung untuk aplikasi ASP.NET Core.

Konfigurasi dalam kode untuk aplikasi konsol .NET/.NET Core

Untuk aplikasi konsol, kodenya sama untuk .NET dan .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Detail operasional ServerTelemetryChannel

ServerTelemetryChannel menyimpan item yang tiba di buffer dalam memori. Item diserialisasikan, dikompresi, dan disimpan ke dalam instans Transmission setiap 30 detik sekali, atau ketika 500 item telah di-buffer. Satu instans Transmission berisi hingga 500 item dan mewakili batch telemetri yang dikirim melalui satu panggilan HTTPS ke layanan Application Insights.

Secara default, maksimum 10 instans Transmission dapat dikirim secara paralel. Jika telemetri tiba dengan tarif yang lebih cepat, atau jika jaringan atau back end Application Insights lambat, instans Transmission disimpan dalam memori. Kapasitas default buffer dalam memori Transmission ini adalah 5 MB. Ketika kapasitas dalam memori telah terlampaui, instans Transmission disimpan pada disk lokal hingga batas 50 MB.

Transmission instans disimpan di disk lokal juga ketika ada masalah jaringan. Hanya item yang disimpan di disk lokal yang selamat dari crash aplikasi. Mereka dikirim setiap kali aplikasi dimulai lagi. Jika masalah jaringan berlanjut, ServerTelemetryChannel akan menggunakan logika backoff eksponensial mulai dari 10 detik hingga 1 jam sebelum mencoba kembali mengirim telemetri.

Pengaturan yang dapat dikonfigurasi di saluran

Untuk daftar lengkap pengaturan yang dapat dikonfigurasi bagi setiap saluran, lihat:

Berikut adalah pengaturan yang paling umum digunakan untuk ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: Jumlah maksimum memori, dalam byte, digunakan oleh saluran untuk buffer transmisi dalam memori. Ketika kapasitas ini tercapai, item baru disimpan langsung ke disk lokal. Nilai defaultnya adalah 5 MB. Mengatur nilai yang lebih tinggi menyebabkan penggunaan disk lebih sedikit, tetapi ingat bahwa item dalam memori akan hilang jika aplikasi crash.
  • MaxTransmissionSenderCapacity: Jumlah maksimum instans Transmission yang akan dikirim ke Application Insights secara bersamaan. Nilai defaultnya adalah 10. Pengaturan ini dapat dikonfigurasi ke angka yang lebih tinggi, yang kami sarankan ketika volume telemetri yang besar dihasilkan. Volume tinggi biasanya terjadi selama pengujian beban atau saat pengambilan sampel dimatikan.
  • StorageFolder: Folder yang digunakan oleh saluran untuk menyimpan item ke disk sesuai kebutuhan. Di Windows, %LOCALAPPDATA% atau %TEMP% digunakan jika tidak ada jalur lain yang ditentukan secara eksplisit. Di lingkungan selain Windows, Anda harus menentukan lokasi atau telemetri yang sahih tidak akan disimpan ke diska lokal.

Saluran mana yang harus saya gunakan?

Kami merekomendasikan ServerTelemetryChannel untuk sebagian besar skenario produksi yang melibatkan aplikasi yang berjalan lama. Metode yang Flush() diterapkan oleh ServerTelemetryChannel tidak sinkron. Ini juga tidak menjamin pengiriman semua item yang tertunda dari memori atau disk.

Jika Anda menggunakan saluran ini dalam skenario di mana aplikasi akan dimatikan, perkenalkan beberapa penundaan setelah Anda memanggil Flush(). Jumlah penundaan yang mungkin Anda perlukan tidak dapat diprediksi. Itu tergantung pada faktor-faktor seperti berapa banyak item atau instans Transmission dalam memori, berapa banyak yang ada di disk, berapa banyak yang ditransmisikan ke back end, dan apakah saluran berada di tengah-tengah skenario back-off eksponensial.

Jika Anda perlu melakukan flush sinkron, gunakan InMemoryChannel.

Pertanyaan yang Sering Ditanyakan

Bagian ini menyediakan jawaban atas pertanyaan umum.

Apakah saluran Application Insights menjamin pengiriman telemetri? Jika tidak, apa skenario di mana telemetri dapat hilang?

Jawaban singkatnya adalah bahwa tidak ada saluran bawaan yang menawarkan jaminan transaksi pengiriman telemetri ke back end. ServerTelemetryChannel lebih maju dibandingkan dengan InMemoryChannel untuk pengiriman yang dapat diandalkan, tetapi juga hanya melakukan upaya terbaik untuk mengirim telemetri. Telemetri masih dapat hilang dalam beberapa situasi, termasuk skenario umum ini:

  • Item dalam memori hilang ketika aplikasi crash.
  • Telemetri hilang selama periode masalah jaringanyang berkepanjangan. Telemetri disimpan ke disk lokal selama pemadaman jaringan atau ketika masalah terjadi dengan back end Application Insights. Namun, item yang lebih lama dari 48 jam akan dibuang.
  • Lokasi diska asali untuk menyimpan telemetri di Windows adalah %LOCALAPPDATA% atau %TEMP%. Lokasi-lokasi ini biasanya lokal ke mesin. Jika aplikasi bermigrasi secara fisik dari satu lokasi ke lokasi lain, setiap telemetri yang disimpan di lokasi asli akan hilang.
  • Di Azure Web Apps di Windows, lokasi penyimpanan disk default adalah D:\local\LocalAppData. Lokasi ini tidak bertahan. Ini dihapus dalam restart aplikasi, peluasan skala, dan operasi lainnya, yang menyebabkan hilangnya telemetri apa pun yang disimpan di sana. Anda dapat mengganti default dan menentukan penyimpanan ke lokasi yang bertahan seperti D:\home. Namun, lokasi yang bertahan seperti itu dilayani oleh penyimpanan jarak jauh dan bisa lambat.

Meskipun lebih kecil kemungkinannya, saluran juga dapat menyebabkan item telemetri duplikat. Perilaku ini terjadi ketika ServerTelemetryChannel percobaan ulang karena kegagalan jaringan atau waktu habis, ketika telemetri dikirimkan ke ujung belakang, tetapi respons hilang karena masalah jaringan atau ada waktu habis.

Apakah ServerTelemetryChannel bekerja pada sistem selain Windows?

Meskipun nama paket dan namespace-nya menyertakan "WindowsServer," saluran ini didukung pada sistem selain Windows, dengan pengecualian berikut. Pada sistem selain Windows, saluran tidak membuat folder penyimpanan lokal secara default. Anda harus membuat folder penyimpanan lokal dan mengonfigurasi saluran untuk menggunakannya. Setelah penyimpanan lokal dikonfigurasi, saluran berfungsi dengan cara yang sama pada semua sistem.

Catatan

Dengan rilis 2.15.0-beta3 dan lebih besar, penyimpanan lokal sekarang secara otomatis dibuat untuk Linux, Mac, dan Windows. Untuk sistem non-Windows, SDK akan secara otomatis membuat folder penyimpanan lokal berdasarkan logika berikut:

  • ${TMPDIR}: Jika ${TMPDIR} variabel lingkungan diatur, lokasi ini digunakan.
  • /var/tmp: Jika lokasi sebelumnya tidak ada, kami mencoba /var/tmp.
  • /tmp: Jika kedua lokasi sebelumnya tidak ada, kami mencoba tmp.
  • Jika tidak ada lokasi tersebut, penyimpanan lokal tidak dibuat dan konfigurasi manual masih diperlukan. Untuk detail implementasi lengkap, lihat repositori GitHub ini.

Apakah SDK membuat penyimpanan lokal sementara? Apakah data dienkripsi di penyimpanan?

SDK menyimpan item telemetri di penyimpanan lokal selama masalah jaringan atau selama pembatasan. Data ini tidak dienkripsi secara lokal.

Untuk sistem Windows, SDK secara otomatis membuat folder lokal sementara di direktori %TEMP% atau %LOCALAPPDATA% dan membatasi akses ke administrator dan pengguna saat ini saja.

Untuk sistem selain Windows, tidak ada penyimpanan lokal yang dibuat secara otomatis oleh SDK, sehingga tidak ada data yang disimpan secara lokal secara default.

Catatan

Dengan rilis 2.15.0-beta3 dan lebih besar, penyimpanan lokal sekarang secara otomatis dibuat untuk Linux, Mac, dan Windows.

Anda dapat membuat direktori penyimpanan sendiri dan mengonfigurasi saluran untuk menggunakannya. Dalam hal ini, Anda bertanggung jawab untuk memastikan bahwa direktori tersebut diamankan. Baca selengkapnya tentang perlindungan data dan privasi.

SDK sumber terbuka

Seperti setiap SDK untuk Application Insights, saluran bersumber terbuka. Baca dan berkontribusi pada kode atau laporkan masalah di repositori GitHub resmi.

Langkah berikutnya