اقرأ باللغة الإنجليزية

مشاركة عبر

تشخيص الاستثناءات في تطبيقات الويب باستخدام Application Insights

  • مقالة

تنبيه

نوصي ب Azure Monitor OpenTelemetry Distro للتطبيقات الجديدة أو العملاء لتشغيل Azure Monitor Application Insights. يوفر Azure Monitor OpenTelemetry Distro وظيفة وتجربة مماثلة ل Application Insights SDK. من الممكن الترحيل من Application Insights SDK باستخدام أدلة الترحيل ل .NET Node.js وPython، ولكننا ما زلنا نعمل على إضافة بعض الميزات الإضافية للتوافق مع الإصدارات السابقة.

يمكن الإبلاغ عن الاستثناءات في تطبيقات الويب باستخدام Application Insights. يمكنك ربط الطلبات الفاشلة بالاستثناءات والأحداث الأخرى على كل من العميل والخادم، بحيث يمكنك تشخيص الأسباب بسرعة. في هذه المقالة، ستتعرف على كيفية إعداد تقارير الاستثناء، والإبلاغ عن الاستثناءات بشكل صريح، وتشخيص حالات الفشل، والمزيد.

إعداد تقارير الاستثناء

يمكنك إعداد Application Insights لتقديم تقرير حول الاستثناءات التي تحدث في الخادم أو العميل. اعتمادًا على النظام الأساسي الذي يعتمد عليه التطبيق، ستحتاج إلى الملحق أو عدة تطوير البرامج المناسبة.

جانب الخادم

للإبلاغ عن استثناءات من تطبيق جانب الملقم الخاص بك، خذ بعين الاعتبار السيناريوهات التالية:

جانب العميل

توفر عدة تطوير البرامج الخاصة بـ JavaScript القدرة على إنشاء تقارير على جانب العميل خاصة بالاستثناءات التي تحدث في مستعرضات الويب. لإعداد تقارير الاستثناءات على العميل، راجع Application Insights الخاص بصفحات الويب.

أُطُر التطبيق

مع بعض أطر عمل التطبيق، يتطلب الأمر مزيدًا من التكوين. ضع في اعتبارك التقنيات التالية:

هام

تركز هذه المقالة بشكل خاص على تطبيقات .NET Framework من منظور مثال التعليمات البرمجية. بعض الأساليب التي تعمل نيابة عن .NET Framework تُعتبر قديمة في عدة تطوير البرامج الخاصة بـ.NET Core. لمزيد من المعلومات، راجع وثائق عدة تطوير البرامج الخاصة بـ.NET Core عند إنشاء تطبيقات باستخدام .NET Core.

تشخيص الاستثناءات باستخدام Visual Studio

افتح حل التطبيق في Visual Studio. قم بتشغيل التطبيق، إما على الخادم الخاص بك أو على جهاز التطوير الخاص بك باستخدام F5. أعد إنشاء الاستثناء.

افتح إطار القياس عن بُعد البحث عن Application Insights في Visual Studio. أثناء تصحيح الأخطاء، حدد خانة القائمة المنسدلة Application Insights.

حدد تقرير استثناء لإظهار تتبع المكدس الخاص به. لفتح ملف التعليمات البرمجية ذات الصلة، حدد مرجع الخط في تتبع المكدس.

إذا تم تمكين CodeLens، فسترى بيانات حول الاستثناءات:

لقطة شاشة توضح إعلام CodeLens الخاص بالاستثناءات.

تشخيص حالات الفشل باستخدام مدخل Azure

يأتي Application Insights مع تجربة إدارة أداء التطبيق المجمّع لمساعدتك على تشخيص الفشل في التطبيقات التي تتم مراقبتها. للبدء، في قائمة مورد Application Insights على اليسار، ضمن Investigate، حدد الخيار Failures.

سترى اتجاهات معدل الفشل لطلباتك، وعدد الطلبات التي تفشل منها، وعدد المستخدمين المتأثرين. تعرض طريقة العرض الشاملة بعض التوزيعات الأكثر فائدة الخاصة بالعملية الفاشلة المحددة. سترى أهم ثلاثة رموز استجابة، وأهم ثلاثة أنواع من الاستثناءات، وأهم ثلاثة أنواع تبعية فاشلة.

لقطة شاشة تعرض طريقة عرض فرز حالات الفشل في علامة التبويب

لمراجعة عينات تمثيلية لكل مجموعة من هذه المجموعات الفرعية من العمليات، حدد الارتباط المطابق. على سبيل المثال، لتشخيص الاستثناءات، يمكنك تحديد عدد مرات حدوث استثناء معين ليتم تقديمه مع علامة التبويب تفاصيل المعاملة من طرف إلى طرف.

لقطة شاشة تعرض علامة التبويب الخاصة بتفاصيل المعاملة الشاملة.

بدلا من ذلك، بدلاً من النظر إلى استثناءات عملية فشل معينة، يمكنك البدء من طريقة العرض الكلي للاستثناءات، عن طريق التبديل إلى علامة التبويب استثناءات الموجودة في الأعلى. هنا يمكنك رؤية جميع الاستثناءات التي تم جمعها للتطبيق الخاص بك الذي تتم مراقبته.

التتبع المخصص وبيانات السجل

للحصول على بيانات تشخيصية خاصة بتطبيقك، يمكنك إدراج تعليمة برمجية لإرسال بيانات القياس عن بُعد الخاصة بك. يتم عرض بيانات القياس عن بُعد أو بيانات السجل المخصصة في البحث التشخيصي إلى جانب الطلب وعرض الصفحة والبيانات الأخرى التي يتم جمعها تلقائياً.

باستخدام Microsoft.VisualStudio.ApplicationInsights.TelemetryClient، تتوفر لديك عدة واجهات برمجة تطبيقات:

لمشاهدة هذه الأحداث، في القائمة اليسرى، افتح البحث. حدد أنواع أحداث القائمة المنسدلة، ثم اختر حدث مخصص أو تتبع أو استثناء.

لقطة شاشة تعرض شاشة البحث.

ملاحظة

إذا كان التطبيق الخاص بك يولد الكثير من القياس عن بُعد، سوف تقلل وحدة أخذ العينات التكيفية تلقائياً من حجم الصوت الذي يتم إرساله إلى المدخل عن طريق إرسال جزء تمثيلي فقط من الأحداث. سيتم تحديد الأحداث التي تشكل جزءًا من العملية نفسها أو إلغاء تحديدها كمجموعة، بحيث يمكنك التنقل بين الأحداث ذات الصلة. لمزيد من المعلومات، راجع أخذ العينات في Application Insights.

رؤية بيانات POST لخاص بالطلب

لا تتضمن تفاصيل الطلب البيانات المرسلة إلى تطبيقك في استدعاء POST. للإبلاغ عن هذه البيانات:

  • تثبيت SDK في مشروع التطبيق الخاص بك.
  • إدراج التعليمات البرمجية في التطبيق الخاص بك لاستدعاء Microsoft.ApplicationInsights.TrackTrace(). إرسال بيانات POST في معلمة الرسالة. يوجد حد للحجم المسموح به، لذلك يجب عليك محاولة إرسال البيانات الأساسية فقط.
  • عند الاستقصاء عن طلب فاشل، ابحث عن عمليات التتبع المقترنة.

التقاط الاستثناءات والبيانات التشخيصية ذات الصلة

في البداية، لن ترى في المدخل جميع الاستثناءات التي تتسبب في الفشل في التطبيق الخاص بك. سترى أي استثناءات خاصة بالمتصفح إذا كنت تستخدم عدة تطوير البرامج JavaScript في صفحات الويب الخاصة بك. ولكن يتم التقاط معظم استثناءات الخادم من قِبل IIS وعليك كتابة قليلاً من التعليمات البرمجية لرؤيتها.

يمكنك:

  • تسجيل الاستثناءات بشكل صريح عن طريق إدخال التعليمة البرمجية في معالجات الاستثناء للإبلاغ عن الاستثناءات.
  • التقاط الاستثناءات تلقائيًا عن طريق تكوين إطار عمل ASP.NET الخاص بك. الإضافات اللازمة مختلفة باختلاف أنواع الإطار.

الإبلاغ عن استثناءات بشكل صريح

الطريقة الأبسط للإبلاغ هي إدخال استدعاء لـ trackException() في معالج الاستثناء.

JavaScript 
try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}
C#‎ 
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);
}
VB 
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

تُعتبر الخصائص ومعلمات القياسات اختيارية، ولكنها مفيدة للمعلومات الإضافية الخاصة بـ التصفية والإضافة. على سبيل المثال، إذا كان لديك تطبيق يمكنه تشغيل العديد من الألعاب، يمكنك العثور على جميع تقارير الاستثناءات المتعلقة بلعبة معينة. يمكنك إضافة العديد من العناصر كما تريد إلى كل قاموس.

استثناءات المستعرض

يتم الإبلاغ عن معظم استثناءات المستعرض.

إذا كانت صفحة الويب الخاصة بك تتضمن ملفات نصية من شبكات تسليم المحتوى أو مجالات أخرى، فتأكد من أن علامة البرنامج النصي تحتوي على السمة crossorigin="anonymous"، وأن الخادم يرسل عناوين CORS. سيسمح لك هذا السلوك بالحصول على تتبع مكدس وتفاصيل استثناءات JavaScript التي لم تتم معالجتها من هذه الموارد.

إعادة استخدام عميل القياس عن بُعد

ملاحظة

نوصي بإنشاء مثيل TelemetryClient مرة واحدة وإعادة استخدامه طوال فترة استخدام التطبيق.

مع "حقن التبعية" (DI) في .NET، و عدة تطوير البرامج المناسبة من .NET وتكوين Application Insights بشكل صحيح لـ DI، يمكنك طلب TelemetryClient كمعلمة دالة إنشائية.

C#‎ 
public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

في المثال السابق، يتم حقن TelemetryClient في الفئة ExampleController.

نماذج ويب

بالنسبة لنماذج الويب، ستتمكن وحدة HTTP النمطية من تجميع الاستثناءات عند عدم وجود عمليات إعادة توجيه تم تكوينها باستخدام CustomErrors. ومع ذلك، عندما يكون لديك عمليات إعادة توجيه نشطة، قم بإضافة الأسطر التالية إلى الدالة Application_Error في Global.asax.cs.

C#‎ 
void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

في المثال السابق، يُعبر _telemetryClient هو متغير ضمن نطاق الفئة من النوع TelemetryClient.

MVC

بدءًا من تطبيق عدة تطوير البرامج على الويب الخاصة بـ Application Insights الإصدار 2.6 (beta 3 والإصدارات الأحدث)، يقوم Application Insights بتجميع الاستثناءات التي لم تتم معالجتها والتي تم طرحها في أساليب وحدات تحكم MVC 5 + تلقائيًا. إذا قمت مسبقًا بإضافة معالج مخصص لتعقب مثل هذه الاستثناءات، يمكنك إزالته لمنع إجراء التعقب المزدوج للاستثناءات.

يوجد العديد من السيناريوهات عندما لا يمكن لعامل تصفية الاستثناء القيام بمعالجة الأخطاء بشكل صحيح، عند طرح الاستثناءات:

  • من الدوال الإنشائية لوحدة التحكم
  • من معالجات الرسائل
  • أثناء التوجيه
  • أثناء إنشاء تسلسل محتوى الاستجابة
  • أثناء بدء تشغيل التطبيق
  • في المهام الخلفية

لا تزال تحتاج كافة الاستثناءات التي تمت معالجتها بواسطة التطبيق إلى تعقبها يدوياً. عادةً ما ينتج عن الاستثناءات التي لم تتم معالجة التي تنشأ من وحدات التحكم 500 استجابة "خطأ داخلي في الخادم". إذا تم إنشاء هذه الاستجابة يدويًا كنتيجة لاستثناء تمت معالجته (أو بدون أي استثناء على الإطلاق)، يتم تعقبه في عملية القياس عن بُعد المقابلة للطلب مع 500 ResultCode. ومع ذلك، فإن عدة تطوير البرامج Application Insights غير قادرة على تتبع استثناء مطابق.

دعم الإصدارات السابقة

إذا كنت تستخدم MVC 4 (والإصدارات الأقدم) من عدة تطوير البرامج على الويب الخاصة بـApplication Insights 2.5 (والإصدارات الأقدم)، راجع الأمثلة التالية لتعقب الاستثناءات.

إذا كان تكوين CustomErrors هو Off، فستتوفر استثناءات للوحدة النمطية HTTP لتقوم بجميعها. ومع ذلك، إذا كان RemoteOnly (هو الوضع الافتراضي)، أو On، سيتم مسح الاستثناء ولن يتوفر لـ Application Insights لإجراء الجمع التلقائي. يمكنك إصلاح ذلك السلوك عن طريق تجاوز الفئة System.Web.Mvc.HandleErrorAttribute، وتطبيق الفئة التي تم تجاوزها كما هو موضح بالنسبة لإصدارات MVC المختلفة أدناه (المصدر GitHub):

C#‎ 
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

استبدل السمة HandleError واستخدام السمة الجديدة في وحدات التحكم الخاصة بك.

C#‎ 
    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

العينة

MVC 3

سجل AiHandleErrorAttribute كعامل تصفية عمومي في Global.asax.cs:

C#‎ 
public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

العينة

MVC 4، MVC 5

سجل AiHandleErrorAttribute كعامل تصفية عمومي في FilterConfig.cs:

C#‎ 
public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

العينة

واجهة API للويب

بدءاً من تطبيق عدة تطوير البرامج على الويب الخاصة بـ Application Insights الإصدار 2.6 (beta 3 والإصدارات الأحدث)، يقوم Application Insights بتجميع الاستثناءات التي لم تتم معالجتها والتي تم طرحها في أساليب وحدة التحكم تلقائيًا بالنسبة لـ Web API 2+. إذا قمت مسبقا بإضافة معالج مخصص لتعقب مثل هذه الاستثناءات كما هو موضح في الأمثلة التالية، يمكنك إزالته لمنع إجراء التعقب المزدوج للاستثناءات.

توجد العديد من الحالات التي لا يمكن فيها لعوامل تصفية الاستثناء القيام بالمعالجة. على سبيل المثال:

  • الاستثناءات التي تم طرحها من الدوال الإنشائية لوحدة التحكم.
  • الاستثناءات التي تم طرحها من معالجات الرسائل.
  • الاستثناءات التي تم طرحها أثناء التوجيه.
  • الاستثناءات التي تم طرحها أثناء إنشاء تسلسل محتوى الاستجابة.
  • الاستثناء الذي تم طرحه أثناء بدء تشغيل التطبيق.
  • الاستثناء الذي تم طرحه في المهام الخلفية.

لا تزال تحتاج كافة الاستثناءات التي تمت معالجتها بواسطة التطبيق إلى تعقبها يدوياً. عادةً ما ينتج عن الاستثناءات التي لم تتم معالجة التي تنشأ من وحدات التحكم 500 استجابة "خطأ داخلي في الخادم". إذا تم إنشاء هذه الاستجابة يدويًا كنتيجة لاستثناء تمت معالجته (أو بدون أي استثناء على الإطلاق)، يتم تعقبه في عملية القياس عن بُعد المقابلة للطلب مع 500 ResultCode. ومع ذلك، فإنه يتعذر على عدة تطوير البرامج Application Insights تتبع استثناء مطابق.

دعم الإصدارات السابقة

إذا كنت تستخدم Web API 1 (والإصدارات الأقدم) من عدة تطوير البرامج على الويب الخاصة بـ Application Insights 2.5 (والإصدارات الأقدم)، راجع الأمثلة التالية لتعقب الاستثناءات.

Web API 1.x

تجاوز System.Web.Http.Filters.ExceptionFilterAttribute:

C#‎ 
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);
    }
    }
}

يمكنك إضافة هذه السمة التي تم تجاوزها إلى وحدات تحكم معينة أو إضافتها إلى تكوين عامل التصفية العمومي في الفئة WebApiConfig:

C#‎ 
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());
        }
    }
}

العينة

Web API 2.x

إضافة تطبيق IExceptionLogger:

C#‎ 
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);
        }
    }
}

أضف هذه القصاصة البرمجية إلى الخدمات في WebApiConfig:

C#‎ 
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());
        }
    }
}

العينة

كبدائل لهذه الإجراءات، يمكنك:

  • استبدل المثيل الوحيد ExceptionHandler بتنفيذ مخصص لـ IExceptionHandler. يتم استدعاء معالج الاستثناء هذا فقط عندما يكون إطار العمل لا يزال قادراً على اختيار رسالة الاستجابة لإرسالها (وليس عند إحباط الاتصال لمثيل)
  • استخدم عوامل تصفية الاستثناء، كما هو موضح في القسم السابق على وحدات تحكم واجهة برمجة تطبيقات الويب 1.x، والتي لا يتم استدعاؤها في جميع الحالات.

WCF

أضف فئة تمتد Attribute وتنفذ IErrorHandler وIServiceBehavior.

C#‎ 
    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)
        {
        }
      }
    }

إضافة السمة إلى تطبيقات الخدمة:

C#‎ 
namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

العينة

عدادات أداء الاستثناء

إذا قمت بتثبيت عامل Azure Monitor Application Insights Agent على الخادم الخاص بك، يمكنك الحصول على مخطط معدل الاستثناءات، التي تم قياسها بواسطة .NET. يتم تضمين كلاً من استثناءات .NET المعالجَة وغير المعالجة.

افتح علامة تبويب مستكشف المقاييس، وأضف مخططًا جديدًا. ضمن عدّادات الأداء، حدد معدل الاستثناء.

يحسب إطار عمل .NET المعدل عن طريق حساب عدد الاستثناءات التي تحدث في فاصل زمني ما وقسمتها على طول الفاصل الزمني.

يختلف هذا عن عدد الاستثناءات المحسوبة بواسطة بوابة Application Insights الذي يحسب تقارير TrackException. تختلف الفواصل الزمنية لأخذ العينات، ولا ترسل عدة تطوير البرامج تقارير TrackException لكافة الاستثناءات المعالجة وغير المعالجة.

الخطوات التالية