Mengonfigurasi Application Insights SDK dengan ApplicationInsights.config atau .xml

  • Artikel

Application Insights .NET SDK terdiri dari banyak paket NuGet. Paket inti menyediakan API untuk mengirim telemetri ke Application Insights. Paket lainnya menyediakan modul dan penginisialisasi telemetri untuk otomatis melacak telemetri dari aplikasi Anda dan konteksnya. Dengan menyesuaikan file konfigurasi, Anda dapat mengaktifkan atau menonaktifkan modul telemetri dan penginisialisasi. Anda juga dapat mengatur parameter untuk beberapa di antaranya.

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.

File konfigurasi diberi nama ApplicationInsights.config atau ApplicationInsights.xml. Nama tergantung pada jenis aplikasi Anda. File ini otomatis ditambahkan ke proyek Anda saat Anda memasang sebagian besar versi SDK. Secara default, saat Anda menggunakan pengalaman otomatis dari proyek templat Visual Studio yang mendukung Tambahkan>Telemetri Application Insights, ApplicationInsights.config file dibuat di folder akar proyek. Saat dikompilasi, file disalin ke folder bin. Ini juga ditambahkan ke aplikasi web oleh Application Insights Agent di server IIS. File konfigurasi diabaikan jika ekstensi untuk situs web Azure atau ekstensi untuk Azure VM dan set skala komputer virtual digunakan.

Tidak ada file yang setara untuk mengontrol SDK di halaman web.

Artikel ini menjelaskan bagian yang Anda lihat dalam file konfigurasi, bagaimana mereka mengontrol komponen SDK, dan paket NuGet mana yang memuat komponen tersebut.

Catatan

Instruksi ApplicationInsights.config dan .xml tidak berlaku untuk .NET Core SDK. Untuk mengonfigurasi aplikasi .NET Core, ikuti instruksi di Application Insights untuk aplikasi ASP.NET Core.

Modul telemetri (ASP.NET)

Setiap modul telemetri mengumpulkan jenis data tertentu dan menggunakan API inti untuk mengirim data. Modul dipasang oleh paket NuGet yang berbeda, yang juga menambahkan baris yang diperlukan ke file .config.

Ada simpul di file konfigurasi untuk setiap modul. Untuk menonaktifkan modul, hapus node atau beri komentar.

Pelacakan dependensi

Pelacakan Dependensi mengumpulkan telemetri tentang panggilan yang dilakukan aplikasi Anda ke database serta layanan dan database eksternal. Untuk memungkinkan modul ini berfungsi di server IIS, Anda perlu menginstal Agen Application Insights.

Anda juga dapat menulis kode pelacakan dependensi Anda sendiri dengan menggunakan API TrackDependency.

Dependensi dapat dikoleksi otomatis tanpa memodifikasi kode Anda dengan menggunakan lampiran berbasis agen (tanpa kode). Untuk menggunakannya di aplikasi web Azure, aktifkan ekstensi Application Insights. Untuk menggunakannya dalam Azure VM atau set skala komputer virtual Azure, aktifkan ekstensi Pemantauan Aplikasi untuk VM dan set skala komputer virtual.

Pengumpul performa

Pengumpul performa mengumpulkan penghitung kinerja sistem, seperti CPU, memori, dan beban jaringan dari penginstalan IIS. Anda dapat menentukan penghitung mana yang akan dikumpulkan, termasuk penghitung kinerja yang telah Anda siapkan sendiri.

Telemetri diagnostik Application Insights

Kelas DiagnosticsTelemetryModule melaporkan kesalahan dalam kode instrumentasi Application Insights itu sendiri. Contohnya adalah jika kode tidak dapat mengakses penghitung kinerja atau jika ITelemetryInitializer melemparkan pengecualian. Jejak telemetri yang dilacak oleh modul ini muncul di Penelusuran Diagnostik.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Paket NuGet Microsoft.ApplicationInsights. Jika Anda hanya menginstal paket ini, file ApplicationInsights.config tidak dibuat secara otomatis.

Mode pengembang

Kelas memaksa DeveloperModeWithDebuggerAttachedTelemetryModule Application Insights TelemetryChannel untuk segera mengirim data, satu item telemetri pada satu waktu, ketika debugger dilampirkan ke proses aplikasi. Desain ini mengurangi jumlah waktu antara saat aplikasi Anda melacak telemetri dan ketika muncul di portal Application Insights. Ini menyebabkan overhead yang signifikan dalam CPU dan bandwidth jaringan.

Pelacakan permintaan web

Pelacakan permintaan web melaporkan waktu respons dan kode hasil permintaan HTTP.

Pelacakan pengecualian

Kelas ExceptionTrackingTelemetryModule melacak pengecualian yang tidak tertangani di aplikasi web Anda. Untuk informasi selengkapnya, lihat Kegagalan dan pengecualian.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Paket NuGet Microsoft.ApplicationInsights.Web .
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Melacak tugas yang tidak ditangguhkan. Pengecualian.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Melacak pengecualian yang tidak tertangani untuk peran pekerja, layanan Windows, dan aplikasi konsol.
  • Paket NuGetApplication Insights Windows Server.

Pelacakan EventSource

Kelas ini EventSourceTelemetryModule memungkinkan Anda mengonfigurasi peristiwa EventSource untuk dikirim ke Application Insights sebagai jejak. Untuk informasi tentang melacak peristiwa EventSource, lihat Menggunakan peristiwa EventSource.

Pelacakan peristiwa ETW

Kelas ini EtwCollectorTelemetryModule memungkinkan Anda mengonfigurasi peristiwa dari penyedia ETW untuk dikirim ke Application Insights sebagai jejak. Untuk informasi tentang melacak peristiwa ETW, lihat Menggunakan peristiwa ETW.

Microsoft.ApplicationInsights

Paket ini Microsoft.ApplicationInsights menyediakan API inti SDK. Modul telemetri lainnya menggunakan API ini. Anda juga dapat menggunakannya untuk menentukan telemetri Anda sendiri.

  • Tidak ada entri di ApplicationInsights.config.
  • Paket NuGet Microsoft.ApplicationInsights. Jika Anda baru saja memasang NuGet ini, tidak ada file .config yang dihasilkan.

Saluran telemetri

Saluran telemetri mengelola buffering dan transmisi telemetri ke layanan Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel adalah saluran bawaan untuk aplikasi web. Ini buffer data dalam memori dan menggunakan mekanisme coba lagi dan penyimpanan disk lokal untuk pengiriman telemetri yang lebih andal.
  • Microsoft.ApplicationInsights.InMemoryChannel adalah saluran telemetri ringan. Ini digunakan jika tidak ada saluran lain yang dikonfigurasi.

Penginisialisasi telemetri (ASP.NET)

Penginisialisasi telemetri mengatur properti konteks yang dikirim bersama dengan setiap item telemetri.

Anda dapat menulis inisialisasi Anda sendiri untuk mengatur properti konteks.

Inisialisasi standar semuanya diatur baik oleh paket Web atau WindowsServer NuGet:

  • AccountIdTelemetryInitializerAccountId mengatur properti .

  • AuthenticatedUserIdTelemetryInitializerAuthenticatedUserId mengatur properti sebagaimana diatur oleh JavaScript SDK.

  • AzureRoleEnvironmentTelemetryInitializer memperbarui properti RoleName dan RoleInstance dari konteks Device untuk semua item telemetri dengan informasi yang diambil dari lingkungan runtime proses Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializer memperbarui properti Version dari konteks Component untuk semua item telemetri dengan nilai yang diekstrak dari file BuildInfo.config yang dihasilkan oleh MS Build.

  • ClientIpHeaderTelemetryInitializerIp memperbarui properti Location konteks semua item telemetri berdasarkan X-Forwarded-For header HTTP permintaan.

  • DeviceTelemetryInitializer memperbarui properti berikut dari konteks Device untuk semua item telemetri.

    • Type diatur ke PC.
    • Id diatur ke nama domain komputer tempat aplikasi web berjalan.
    • OemName diatur ke nilai yang diekstrak dari Win32_ComputerSystem.Manufacturer bidang dengan menggunakan WMI.
    • Model diatur ke nilai yang diekstrak dari Win32_ComputerSystem.Model bidang dengan menggunakan WMI.
    • NetworkType diatur ke nilai yang diekstrak dari NetworkInterface properti .
    • Language diatur ke nama CurrentCulture properti.

  • DomainNameRoleInstanceTelemetryInitializer memperbarui properti RoleInstance dari konteks Device untuk semua item telemetri dengan nama domain komputer tempat aplikasi web berjalan.

  • OperationNameTelemetryInitializerName memperbarui properti RequestTelemetry dan Name properti Operation konteks semua item telemetri berdasarkan metode HTTP, dan nama pengontrol dan tindakan MVC ASP.NET yang dipanggil untuk memproses permintaan.

  • OperationIdTelemetryInitializer atau OperationCorrelationTelemetryInitializer memperbarui Operation.Id properti konteks dari semua item telemetri yang dilacak saat menangani permintaan dengan RequestTelemetry.Id yang dibuat secara otomatis.

  • SessionTelemetryInitializerId memperbarui properti Session konteks untuk semua item telemetri dengan nilai yang diekstrak dari ai_session cookie yang dihasilkan oleh ApplicationInsights kode instrumentasi JavaScript yang berjalan di browser pengguna.

  • SyntheticTelemetryInitializer atau SyntheticUserAgentTelemetryInitializer memperbarui Userproperti konteks , , Sessiondan Operation dari semua item telemetri yang dilacak saat menangani permintaan dari sumber sintetis, seperti uji ketersediaan atau bot mesin pencari. Secara default, penjelajah metrik tidak menampilkan telemetri sintetis.

    <Filters> mengatur properti pengidentifikasi permintaan.

  • UserTelemetryInitializerId memperbarui properti User dan AcquisitionDate konteks untuk semua item telemetri dengan nilai yang diekstrak dari ai_user cookie yang dihasilkan oleh kode instrumentasi JavaScript Application Insights yang berjalan di browser pengguna.

  • WebTestTelemetryInitializer mengatur ID pengguna, ID sesi, dan properti sumber sintetis untuk permintaan HTTP yang berasal dari pengujian ketersediaan. <Filters> mengatur properti pengidentifikasi permintaan.

Untuk aplikasi .NET yang berjalan di Azure Service Fabric, Anda dapat menyertakan Microsoft.ApplicationInsights.ServiceFabric paket NuGet. Paket ini mencakup FabricTelemetryInitializer properti, yang menambahkan properti Service Fabric ke item telemetri. Untuk informasi lebih lanjut, lihat halaman GitHub tentang properti yang ditambahkan oleh paket NuGet ini.

Prosesor telemetri (ASP.NET)

Prosesor telemetri dapat memfilter dan memodifikasi setiap item telemetri sebelum dikirim dari SDK ke portal.

Anda dapat menulis prosesor telemetri Anda sendiri.

Prosesor telemetri pengambilan sampel adaptif (dari 2.0.0-beta3)

Fungsionalitas ini diaktifkan secara default. Jika aplikasi Anda mengirimkan banyak telemetri, prosesor ini akan menghapus sebagian telemetri tersebut.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

Parameter memberikan target yang coba dicapai oleh algoritme. Setiap instans SDK berfungsi secara independen. Jadi, jika server Anda adalah kluster beberapa komputer, volume telemetri aktual akan dikalikan dengan sesuai.

Pelajari lebih lanjut tentang pengambilan sampel.

Prosesor telemetri pengambilan sampel laju tetap (dari 2.0.0-beta1)

Ada juga prosesor telemetri pengambilan sampel standar (dari 2.0.1):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

Lihat sampel kode string koneksi.

InstrumentationKey

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, namun kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

Pengaturan ini menentukan sumber daya Application Insights tempat data Anda muncul. Biasanya, Anda membuat sumber daya terpisah, dengan kunci terpisah, untuk setiap aplikasi Anda.

Jika Anda ingin mengatur kunci secara dinamis, misalnya, jika Anda ingin mengirim hasil dari aplikasi ke sumber daya yang berbeda, Anda dapat menghilangkan kunci dari file konfigurasi dan mengaturnya dalam kode sebagai gantinya.

Untuk mengatur kunci untuk semua instans , termasuk modul telemetri standar, lakukan langkah ini dalam metode inisialisasi TelemetryClient, seperti global.aspx.cs dalam layanan ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Jika Anda ingin mengirim serangkaian peristiwa tertentu ke sumber daya yang berbeda, Anda dapat mengatur kunci untuk klien telemetri tertentu:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Untuk mendapatkan kunci baru, buat sumber daya baru di portal Application Insights.

Penyedia Id Aplikasi

Penyedia tersedia mulai dari v2.6.0.

Tujuan penyedia ini adalah untuk mencari ID aplikasi berdasarkan kunci instrumentasi. ID aplikasi disertakan dalam RequestTelemetry dan DependencyTelemetry digunakan untuk menentukan korelasi di portal.

Fungsionalitas ini tersedia dengan mengatur TelemetryConfiguration.ApplicationIdProvider baik dalam kode atau dalam file konfigurasi.

Antarmuka: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Kami menyediakan dua implementasi di Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider dan DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Wrapper ini ditujukan untuk Profile API kami. Ini akan membatasi permintaan dan hasil cache.

Penyedia ini ditambahkan ke file konfigurasi Anda saat Anda menginstal Microsoft.ApplicationInsights.DependencyCollector atau Microsoft.ApplicationInsights.Web.

Kelas ini memiliki properti opsional ProfileQueryEndpoint. Secara default, diatur ke https://dc.services.visualstudio.com/api/profiles/{0}/appId. Jika Anda perlu mengonfigurasi proksi untuk konfigurasi ini, kami sarankan Anda mem-proxy alamat dasar dan menyertakan "/api/profiles/{0}/appId". {0} diganti pada runtime per permintaan dengan kunci instrumentasi.

Contoh konfigurasi melalui ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Contoh konfigurasi melalui kode

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Penyedia statis ini bergantung pada pasangan kunci instrumentasi/ID aplikasi yang dikonfigurasi.

Kelas ini memiliki Defined properti, yang merupakan Dictionary<string,string> pasangan kunci instrumentasi/ID aplikasi.

Kelas ini memiliki properti Nextopsional , yang dapat digunakan untuk mengonfigurasi penyedia lain untuk digunakan ketika kunci instrumentasi diminta yang tidak ada dalam konfigurasi Anda.

Contoh konfigurasi melalui ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Contoh konfigurasi melalui kode

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Mengonfigurasi koleksi rekam jepret untuk aplikasi ASP.NET

Konfigurasikan koleksi rekam jepret untuk aplikasi ASP.NET.

Langkah berikutnya

Pelajari selengkapnya tentang API