Mengonfigurasi Application Insights SDK dengan ApplicationInsights.config atau .xml
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.
Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
- Paket NuGet Microsoft.ApplicationInsights.DependencyCollector
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.
Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
- Paket NuGet Microsoft.ApplicationInsights.PerfCounterCollector
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.
Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
- Paket NuGet Application Insights Windows Server
Pelacakan permintaan web
Pelacakan permintaan web melaporkan waktu respons dan kode hasil permintaan HTTP.
Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
- Paket NuGet Microsoft.ApplicationInsights.Web
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.
Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
- Microsoft.ApplicationInsights.EventSourceListener
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.EtwCollector.EtwCollectorTelemetryModule
- Microsoft.ApplicationInsights.EtwCollector
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:
AccountIdTelemetryInitializer
AccountId
mengatur properti .AuthenticatedUserIdTelemetryInitializer
AuthenticatedUserId
mengatur properti sebagaimana diatur oleh JavaScript SDK.AzureRoleEnvironmentTelemetryInitializer
memperbarui propertiRoleName
danRoleInstance
dari konteksDevice
untuk semua item telemetri dengan informasi yang diambil dari lingkungan runtime proses Azure.BuildInfoConfigComponentVersionTelemetryInitializer
memperbarui propertiVersion
dari konteksComponent
untuk semua item telemetri dengan nilai yang diekstrak dari fileBuildInfo.config
yang dihasilkan oleh MS Build.ClientIpHeaderTelemetryInitializer
Ip
memperbarui propertiLocation
konteks semua item telemetri berdasarkanX-Forwarded-For
header HTTP permintaan.DeviceTelemetryInitializer
memperbarui properti berikut dari konteksDevice
untuk semua item telemetri.Type
diatur kePC
.Id
diatur ke nama domain komputer tempat aplikasi web berjalan.OemName
diatur ke nilai yang diekstrak dariWin32_ComputerSystem.Manufacturer
bidang dengan menggunakan WMI.Model
diatur ke nilai yang diekstrak dariWin32_ComputerSystem.Model
bidang dengan menggunakan WMI.NetworkType
diatur ke nilai yang diekstrak dariNetworkInterface
properti .Language
diatur ke namaCurrentCulture
properti.
DomainNameRoleInstanceTelemetryInitializer
memperbarui propertiRoleInstance
dari konteksDevice
untuk semua item telemetri dengan nama domain komputer tempat aplikasi web berjalan.OperationNameTelemetryInitializer
Name
memperbarui propertiRequestTelemetry
danName
propertiOperation
konteks semua item telemetri berdasarkan metode HTTP, dan nama pengontrol dan tindakan MVC ASP.NET yang dipanggil untuk memproses permintaan.OperationIdTelemetryInitializer
atauOperationCorrelationTelemetryInitializer
memperbaruiOperation.Id
properti konteks dari semua item telemetri yang dilacak saat menangani permintaan denganRequestTelemetry.Id
yang dibuat secara otomatis.SessionTelemetryInitializer
Id
memperbarui propertiSession
konteks untuk semua item telemetri dengan nilai yang diekstrak dariai_session
cookie yang dihasilkan olehApplicationInsights
kode instrumentasi JavaScript yang berjalan di browser pengguna.SyntheticTelemetryInitializer
atauSyntheticUserAgentTelemetryInitializer
memperbaruiUser
properti konteks , ,Session
danOperation
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.UserTelemetryInitializer
Id
memperbarui propertiUser
danAcquisitionDate
konteks untuk semua item telemetri dengan nilai yang diekstrak dariai_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 Next
opsional , 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
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk