Mendiagnosis pengecualian di aplikasi web dengan Application Insights
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.
Pengecualian dalam aplikasi web dapat dilaporkan dengan Application Insights. Anda dapat menghubungkan permintaan yang gagal dengan pengecualian dan peristiwa lain pada klien dan server agar Anda dapat dengan cepat mendiagnosis penyebabnya. Dalam artikel ini, Anda akan mempelajari cara menyiapkan pelaporan pengecualian, melaporkan pengecualian secara eksplisit, mendiagnosis kegagalan, dan lainnya.
Menyiapkan pelaporan pengecualian
Anda dapat menyiapkan Application Insights untuk melaporkan pengecualian yang terjadi pada server maupun pada klien. Anda akan memerlukan ekstensi atau SDK yang sesuai, bergantung pada platform yang digunakan aplikasi Anda.
Sisi peladen
Untuk memiliki pengecualian yang dilaporkan dari aplikasi sisi server Anda, pertimbangkan skenario berikut:
- Tambahkan Ekstensi Application Insights untuk aplikasi web Azure.
- Tambahkan Ekstensi Pemantauan Aplikasi untuk Azure Virtual Machines dan Azure Virtual Machine Scale Sets aplikasi yang dihosting IIS.
- Instal SDK Application Insights di kode aplikasi Anda, jalankan Agen Application Insights untuk server web IIS, atau aktifkan agen Java untuk aplikasi web Java.
Sisi klien
SDK JavaScript menyediakan kemampuan pelaporan pengecualian sisi klien yang terjadi di browser web. Untuk menyiapkan pelaporan pengecualian pada klien, lihat Application Insights untuk halaman web.
Kerangka kerja aplikasi
Dengan beberapa kerangka kerja aplikasi, diperlukan lebih banyak konfigurasi. Pertimbangkan teknologi berikut:
Penting
Artikel ini secara khusus berfokus pada aplikasi .NET Framework dari perspektif contoh kode. Beberapa metode yang bekerja untuk .NET Framework sudah usang dalam .NET Core SDK. Untuk informasi selengkapnya, lihat dokumentasi .NET Core SDK saat membuat aplikasi dengan .NET Core.
Mendiagnosis pengecualian menggunakan Visual Studio
Buka solusi di Visual Studio. Jalankan aplikasi, baik di server Anda atau di mesin pengembangan Anda dengan menggunakan F5. Buat ulang pengecualian.
Buka jendela telemetri Pencarian Application Insights di Visual Studio. Saat melakukan penelusuran kesalahan, pilih kotak dropdown Application Insights.
Pilih laporan pengecualian untuk menampilkan jejak tumpukannya. Untuk membuka file kode yang relevan, pilih referensi baris di pelacakan tumpukan.
Jika CodeLens diaktifkan, Anda akan melihat data tentang pengecualian:
Mendiagnosis kegagalan menggunakan portal Azure
Application Insights dilengkapi dengan pengalaman Manajemen Performa Aplikasi (APM) yang dikumpulkan untuk membantu Anda mendiagnosis kegagalan dalam aplikasi yang dipantau. Untuk memulai, di menu sumber daya Application Insights sebelah kiri, di bagian Selidiki, pilih opsi Kegagalan.
Anda akan melihat tren tingkat kegagalan untuk permintaan Anda, jumlah kegagalan, dan jumlah pengguna yang terkena dampak. Tampilan Keseluruhan menunjukkan beberapa distribusi paling berguna, khusus untuk operasi gagal yang dipilih. Anda akan melihat tiga kode respons teratas, tiga jenis pengecualian teratas, dan tiga jenis ketergantungan teratas yang gagal.
Untuk meninjau sampel perwakilan setiap subkumpulan operasi ini, pilih tautan yang sesuai. Sebagai contoh, untuk mendiagnosis pengecualian, Anda dapat memilih hitungan pengecualian tertentu untuk disajikan dalam tab Detail Transaksi menyeluruh.
Atau, daripada melihat pengecualian operasi tertentu yang gagal, Anda dapat memulai dari tampilan pengecualian Keseluruhan dengan beralih ke tab Pengecualian di bagian atas. Di sini, Anda dapat melihat semua pengecualian yang dikumpulkan untuk aplikasi yang dipantau.
Pelacakan kustom dan data log
Untuk mendapatkan data diagnostik khusus untuk aplikasi, Anda dapat menyisipkan kode untuk mengirim data telemetri Anda sendiri. Telemetri kustom atau data log Anda ditampilkan dalam pencarian diagnostik beserta permintaan, tampilan halaman, dan data lain yang dikumpulkan secara otomatis.
Dengan menggunakan Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, Anda memiliki beberapa API yang tersedia:
- TelemetryClient.TrackEvent biasanya digunakan untuk memantau pola penggunaan, tetapi data yang dikirimnya juga muncul di bawah Peristiwa Kustom dalam pencarian diagnostik. Peristiwa diberi nama dan dapat membawa properti string dan metrik numerik tempat Anda dapat memfilter pencarian diagnostik Anda.
- TelemetryClient.TrackTrace memungkinkan Anda mengirim data yang lebih panjang seperti informasi POST.
- TelemetryClient.TrackException mengirimkan detail pengecualian, seperti pelacakan tumpukan ke Application Insights.
Untuk melihat peristiwa ini, di menu sebelah kiri, buka Pencarian. Pilih menu dropdown Jenis peristiwa, lalu pilih Peristiwa Kustom, Jejak, atau Pengecualian.
Catatan
Jika aplikasi Anda menghasilkan banyak telemetri, modul pengambilan sampel adaptif akan secara otomatis mengurangi volume yang dikirim ke portal dengan hanya mengirimkan sebagian kecil peristiwa yang representatif. Peristiwa yang merupakan bagian dari operasi yang sama akan dipilih atau tidak dipilih sebagai grup, sehingga Anda dapat menavigasi di antara peristiwa terkait. Untuk informasi selengkapnya, lihat Mengambil sampel di Application Insights.
Melihat data POST permintaan
Detail permintaan tidak menyertakan data yang dikirim ke aplikasi Anda dalam panggilan POST. Agar data ini dilaporkan:
- Instal SDK di proyek aplikasi Anda.
- Masukkan kode dalam aplikasi Anda untuk memanggil Microsoft.ApplicationInsights.TrackTrace(). Kirim data POST dalam parameter pesan. Ada batas ukuran yang diizinkan, jadi Anda harus mencoba mengirim data yang penting saja.
- Saat Anda menyelidiki permintaan yang gagal, temukan jejak terkait.
Mengambil pengecualian dan data diagnostik yang terkait
Pada awalnya, Anda tidak akan melihat di portal semua pengecualian yang menyebabkan kegagalan di aplikasi Anda. Anda akan melihat pengecualian browser apa pun, jika Anda menggunakan SDK JavaScript di halaman web Anda. Tetapi sebagian besar pengecualian server ditangkap oleh IIS dan Anda harus menulis sedikit kode untuk melihatnya.
Anda dapat:
- Mencatat pengecualian secara eksplisit dengan memasukkan kode dalam penangan pengecualian untuk melaporkan pengecualian.
- Menangkap pengecualian secara otomatis dengan mengonfigurasi kerangka kerja ASP.NET Anda. Penambahan yang diperlukan berbeda untuk berbagai jenis kerangka kerja.
Melaporkan pengecualian secara eksplisit
Cara paling sederhana untuk melaporkan adalah dengan menyisipkan panggilan ke trackException() di penghandel pengecualian.
try
{
// ...
}
catch (ex)
{
appInsights.trackException(ex, "handler loc",
{
Game: currentGame.Name,
State: currentGame.State.ToString()
});
}
var telemetry = new TelemetryClient();
try
{
// ...
}
catch (Exception ex)
{
var properties = new Dictionary<string, string>
{
["Game"] = currentGame.Name
};
var measurements = new Dictionary<string, double>
{
["Users"] = currentGame.Users.Count
};
// Send the exception telemetry:
telemetry.TrackException(ex, properties, measurements);
}
Dim telemetry = New TelemetryClient
Try
' ...
Catch ex as Exception
' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("Game", currentGame.Name)
Dim measurements = New Dictionary (Of String, Double)
measurements.Add("Users", currentGame.Users.Count)
' Send the exception telemetry:
telemetry.TrackException(ex, properties, measurements)
End Try
Parameter properti dan pengukuran bersifat opsional, tetapi berguna untuk memfilter dan menambahkan informasi tambahan. Misalnya, jika Anda memiliki aplikasi yang dapat menjalankan beberapa game, Anda dapat menemukan semua laporan pengecualian yang terkait dengan game tertentu. Anda dapat menambahkan item sebanyak yang Anda suka ke setiap kamus.
Pengecualian browser
Sebagian besar pengecualian browser dilaporkan.
Jika halaman web Anda menyertakan berkas skrip dari jaringan pengiriman konten atau domain lain, pastikan tag skrip Anda memiliki atribut crossorigin="anonymous" dan server mengirimkan header CORS. Perilaku ini akan memungkinkan Anda mendapatkan pelacakan tumpukan dan detail untuk pengecualian JavaScript yang tidak ditangani dari sumber daya ini.
Menggunakan kembali klien telemetri Anda
Catatan
Kami menyarankan agar Anda membuat instans TelemetryClient sekali dan menggunakannya kembali sepanjang masa pakai aplikasi.
Dengan Injeksi Dependensi (DI) di .NET, SDK .NET yang sesuai, dan mengonfigurasi Application Insights untuk DI dengan benar, Anda dapat memerlukan TelemetryClient sebagai parameter konstruktor.
public class ExampleController : ApiController
{
private readonly TelemetryClient _telemetryClient;
public ExampleController(TelemetryClient telemetryClient)
{
_telemetryClient = telemetryClient;
}
}
Dalam contoh sebelumnya, TelemetryClient dimasukkan ke dalam kelas ExampleController.
Formulir web
Untuk formulir web, Modul HTTP dapat mengumpulkan pengecualian ketika tidak ada pengalihan yang dikonfigurasi dengan CustomErrors. Namun, ketika Anda memiliki pengalihan aktif, tambahkan baris berikut ke fungsi Application_Error di Global.asax.cs.
void Application_Error(object sender, EventArgs e)
{
if (HttpContext.Current.IsCustomErrorEnabled &&
Server.GetLastError () != null)
{
_telemetryClient.TrackException(Server.GetLastError());
}
}
Dalam contoh sebelumnya, _telemetryClient adalah variabel yang dicakup kelas dari jenis TelemetryClient.
MVC
Mulai dengan Application Insights Web SDK versi 2.6 (beta3 dan yang lebih baru), Application Insights mengumpulkan pengecualian yang tidak tertangani di metode pengontrol MVC 5+ secara otomatis. Jika Anda menambahkan penghandel kustom untuk melacak pengecualian tersebut, Anda dapat menghapusnya untuk mencegah pelacakan ganda pada pengecualian.
Ada beberapa skenario ketika filter pengecualian tidak dapat menangani kesalahan dengan benar saat pengecualian ditampilkan:
- Dari konstruktor pengontrol
- Dari penghandel pesan
- Selama perutean
- Selama serialisasi konten respons
- Selama start-up aplikasi
- Dalam proses di latar belakang
Semua pengecualian yang ditangani oleh aplikasi masih perlu dilacak secara manual. Pengecualian yang tidak tertangani yang berasal dari pengontrol biasanya menghasilkan 500 respons "Kesalahan Server Internal". Jika respons tersebut dibuat secara manual sebagai hasil dari pengecualian yang dihandel, atau tanpa pengecualian sama sekali, respons tersebut dilacak dalam telemetri permintaan yang sesuai dengan ResultCode 500. Namun, Application Insights SDK tidak dapat melacak pengecualian yang sesuai.
Dukungan versi sebelumnya
Jika Anda menggunakan MVC 4 (dan sebelumnya) dari Application Insights Web SDK 2.5 (dan sebelumnya), lihat contoh berikut untuk melacak pengecualian.
Jika konfigurasi CustomErrors adalah Off, pengecualian akan tersedia untuk Modul HTTP yang akan dikumpulkan. Namun, jika konfigurasinya RemoteOnly (default), atau On, pengecualian akan dihapus dan tidak tersedia dalam Application Insights yang akan dikumpulkan secara otomatis. Anda dapat memperbaikinya dengan menimpa kelas System.Web.Mvc.HandleErrorAttribute, dan menerapkan kelas yang ditimpa seperti yang ditunjukkan untuk versi MVC yang berbeda di sini (lihat sumber GitHub):
using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;
namespace MVC2App.Controllers
{
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
public class AiHandleErrorAttribute : HandleErrorAttribute
{
public override void OnException(ExceptionContext filterContext)
{
if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
{
//The attribute should track exceptions only when CustomErrors setting is On
//if CustomErrors is Off, exceptions will be caught by AI HTTP Module
if (filterContext.HttpContext.IsCustomErrorEnabled)
{ //Or reuse instance (recommended!). See note above.
var ai = new TelemetryClient();
ai.TrackException(filterContext.Exception);
}
}
base.OnException(filterContext);
}
}
}
MVC 2
Ganti atribut HandleError dengan atribut baru di pengontrol Anda:
namespace MVC2App.Controllers
{
[AiHandleError]
public class HomeController : Controller
{
// Omitted for brevity
}
}
MVC 3
Mendaftar AiHandleErrorAttribute sebagai filter global di Global.asax.cs:
public class MyMvcApplication : System.Web.HttpApplication
{
public static void RegisterGlobalFilters(GlobalFilterCollection filters)
{
filters.Add(new AiHandleErrorAttribute());
}
}
MVC 4, MVC 5
Mendaftar AiHandleErrorAttribute sebagai filter global di FilterConfig.cs:
public class FilterConfig
{
public static void RegisterGlobalFilters(GlobalFilterCollection filters)
{
// Default replaced with the override to track unhandled exceptions
filters.Add(new AiHandleErrorAttribute());
}
}
API Web
Mulai dengan Application Insights Web SDK versi 2.6 (beta3 dan yang lebih baru), Application Insights mengumpulkan pengecualian yang tidak dihandel yang ditampilkan di metode pengontrol untuk Web API 2+ secara otomatis. Jika sebelumnya Anda telah menambahkan penghandel kustom untuk melacak pengecualian tersebut, seperti yang dijelaskan dalam contoh berikut, Anda dapat menghapusnya untuk mencegah pelacakan ganda pada pengecualian.
Ada beberapa kasus yang tidak dapat ditangani oleh filter pengecualian. Contohnya:
- Pengecualian dari konstruktor pengontrol.
- Pengecualian dari pengelola pesan.
- Pengecualian saat perutean.
- Pengecualian selama serialisasi konten respons.
- Pengecualian ditampilkan selama aplikasi dimulai.
- Pengecualian tugas latar belakang.
Semua pengecualian yang ditangani oleh aplikasi masih perlu dilacak secara manual. Pengecualian yang tidak tertangani yang berasal dari pengontrol biasanya menghasilkan 500 respons "Kesalahan Server Internal". Jika respons semacam itu dibuat secara manual sebagai hasil dari pengecualian yang dihandel, atau tanpa pengecualian sama sekali, respons tersebut dilacak dalam telemetri permintaan yang sesuai dengan ResultCode 500. Namun, SDK Application Insights tidak dapat melacak pengecualian yang sesuai.
Dukungan versi sebelumnya
Jika Anda menggunakan Web API 1 (dan versi sebelumnya) dari Application Insights Web SDK 2.5 (dan versi sebelumnya), lihat contoh berikut untuk melacak pengecualian.
API Web 1.x
Mengambil alih System.Web.Http.Filters.ExceptionFilterAttribute:
using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;
namespace WebAPI.App_Start
{
public class AiExceptionFilterAttribute : ExceptionFilterAttribute
{
public override void OnException(HttpActionExecutedContext actionExecutedContext)
{
if (actionExecutedContext != null && actionExecutedContext.Exception != null)
{ //Or reuse instance (recommended!). See note above.
var ai = new TelemetryClient();
ai.TrackException(actionExecutedContext.Exception);
}
base.OnException(actionExecutedContext);
}
}
}
Anda dapat menambahkan atribut yang diambil alih ini ke pengontrol tertentu, atau menambahkannya ke konfigurasi filter global di kelas WebApiConfig:
using System.Web.Http;
using WebApi1.x.App_Start;
namespace WebApi1.x
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional });
// ...
config.EnableSystemDiagnosticsTracing();
// Capture exceptions for Application Insights:
config.Filters.Add(new AiExceptionFilterAttribute());
}
}
}
API Web 2.x
Tambahkan implementasi IExceptionLogger:
using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;
namespace ProductsAppPureWebAPI.App_Start
{
public class AiExceptionLogger : ExceptionLogger
{
public override void Log(ExceptionLoggerContext context)
{
if (context != null && context.Exception != null)
{
//or reuse instance (recommended!). see note above
var ai = new TelemetryClient();
ai.TrackException(context.Exception);
}
base.Log(context);
}
}
}
Tambahkan cuplikan ini ke layanan di WebApiConfig:
using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;
namespace WebApi2WithMVC
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API configuration and services
// Web API routes
config.MapHttpAttributeRoutes();
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional });
config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
}
}
}
Sebagai alternatif, Anda dapat:
- Ganti satu-satunya instans
ExceptionHandlerdengan penerapanIExceptionHandlerkustom. Penghandel pengecualian ini hanya dipanggil ketika kerangka kerja masih dapat memilih pesan respons mana yang akan dikirim, bukan saat koneksi dibatalkan, misalnya. - Menggunakan filter pengecualian, seperti yang dijelaskan di bagian pada pengontrol Web API 1.x sebelumnya - tidak dipanggil dalam semua kasus.
WCF
Tambahkan kelas yang memperluas Attribute dan mengimplementasikan IErrorHandler dan IServiceBehavior.
using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel.Description;
using System.ServiceModel.Dispatcher;
using System.Web;
using Microsoft.ApplicationInsights;
namespace WcfService4.ErrorHandling
{
public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
{
public void AddBindingParameters(ServiceDescription serviceDescription,
System.ServiceModel.ServiceHostBase serviceHostBase,
System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
{
}
public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
System.ServiceModel.ServiceHostBase serviceHostBase)
{
foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
{
disp.ErrorHandlers.Add(this);
}
}
public void Validate(ServiceDescription serviceDescription,
System.ServiceModel.ServiceHostBase serviceHostBase)
{
}
bool IErrorHandler.HandleError(Exception error)
{//or reuse instance (recommended!). see note above
var ai = new TelemetryClient();
ai.TrackException(error);
return false;
}
void IErrorHandler.ProvideFault(Exception error,
System.ServiceModel.Channels.MessageVersion version,
ref System.ServiceModel.Channels.Message fault)
{
}
}
}
Tambahkan atribut ke implementasi layanan:
namespace WcfService4
{
[AiLogException]
public class Service1 : IService1
{
// Omitted for brevity
}
}
Penghitung kinerja pengecualian
Jika Anda telah menginstal Agen Application Insights Azure Monitor di server Anda, Anda bisa mendapatkan bagan tingkat pengecualian, yang diukur dengan .NET. Pengecualian .NET yang dihandel dan tidak dihandel juga disertakan.
Buka tab penjelajah metrik, tambahkan bagan baru. Di Penghitung Kinerja, pilih Tingkat pengecualian.
.NET Framework menghitung tarif dengan menghitung jumlah pengecualian dalam interval dan membaginya dengan panjang interval.
Jumlah ini berbeda dengan jumlah 'Pengecualian' yang dihitung oleh portal Application Insights yang menghitung laporan TrackException. Interval pengambilan sampel berbeda, dan SDK tidak mengirim laporan TrackException untuk semua pengecualian yang dihandel dan tidak dihandel.