تمكين Azure Monitor Application Insights Real User Monitoring

  • مقالة

يجمع Microsoft Azure Monitor Application Insights JavaScript SDK بيانات الاستخدام، والتي تسمح لك بمراقبة وتحليل أداء تطبيقات الويب JavaScript. يشار إلى هذا عادة باسم Real User Monitoring أو RUM.

يحتوي Application Insights JavaScript SDK على SDK أساسي والعديد من المكونات الإضافية لمزيد من القدرات.

Conceptual diagram that shows the Application Insights JavaScript SDK, its plugins/extensions, and their relationship to each other.

نقوم بتجميع طرق عرض الصفحة بشكل افتراضي. ولكن إذا كنت تريد أيضا جمع النقرات بشكل افتراضي، ففكر في إضافة المكون الإضافي Click Analytics Auto-Collection:

  • إذا كنت تضيف ملحق إطار عمل، والذي يمكنك إضافته بعد اتباع الخطوات للبدء أدناه، يمكنك اختياريا إضافة Click Analytics عند إضافة ملحق إطار العمل.
  • إذا كنت لا تضيف ملحق إطار عمل، فقم بإضافة المكون الإضافي Click Analytics بعد اتباع الخطوات للبدء.

نحن نقدم المكون الإضافي لتتبع الأخطاء والمكون الإضافي للأداء لتصحيح الأخطاء/الاختبار. في حالات نادرة، من الممكن إنشاء ملحق خاص بك عن طريق إضافة مكون إضافي مخصص.

المتطلبات الأساسية

الشروع في العمل

اتبع الخطوات الواردة في هذا القسم لوضع علامة على تطبيقك باستخدام Application Insights JavaScript SDK.

تلميح

أخبار طيبة! نحن نسهل تمكين JavaScript. تحقق من مكان إدراج برنامج JavaScript (Web) SDK Loader Script حسب التكوين المتوفر!

إضافة التعليمات البرمجية ل JavaScript

تتوفر طريقتان لإضافة التعليمات البرمجية لتمكين Application Insights عبر Application Insights JavaScript SDK:

الطريقة متى يمكنني استخدام هذا الأسلوب؟
JavaScript (Web) SDK Loader Script بالنسبة لمعظم العملاء، نوصي باستخدام برنامج JavaScript (Web) SDK Loader Script لأنك لن تضطر أبدا إلى تحديث SDK والحصول على آخر التحديثات تلقائيا. أيضا، لديك التحكم في الصفحات التي تضيف إليها Application Insights JavaScript SDK.
حزمة NPM تريد إحضار SDK إلى التعليمات البرمجية الخاصة بك وتمكين IntelliSense. هذا الخيار مطلوب فقط للمطورين الذين يحتاجون إلى المزيد من الأحداث المخصصة والتكوين. هذا الأسلوب مطلوب إذا كنت تخطط لاستخدام React أو React Native أو Angular Framework Extension.

  1. الصق برنامج JavaScript (Web) SDK Loader Script في أعلى كل صفحة تريد تمكين Application Insights لها.

    يفضل أن تقوم بإضافته كأول برنامج نصي في القسم الخاص بك <head> بحيث يمكنه مراقبة أي مشكلات محتملة مع جميع تبعياتك.

    إذا تم الكشف عن Internet Explorer 8، يتم تحميل JavaScript SDK v2.x تلقائيا.

    <script type="text/javascript">
!(function (cfg){function e(){cfg.onInit&&cfg.onInit(i)}var S,u,D,t,n,i,C=window,x=document,w=C.location,I="script",b="ingestionendpoint",E="disableExceptionTracking",A="ai.device.";"instrumentationKey"[S="toLowerCase"](),u="crossOrigin",D="POST",t="appInsightsSDK",n=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=n),i=C[n]||function(l){var d=!1,g=!1,f={initialize:!0,queue:[],sv:"7",version:2,config:l};function m(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[A+"id"]=i[S](),n[A+"type"]=i,n["ai.operation.name"]=w&&w.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(f.sv||f.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:4,seq:"1",aiDataContract:undefined}}var h=-1,v=0,y=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],k=l.url||cfg.src;if(k){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~k.indexOf("ai.3")&&(k=k.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<y.length;e++)if(0<k.indexOf(y[e])){h=e;break}var i=function(e){var a,t,n,i,o,r,s,c,p,u;f.queue=[],g||(0<=h&&v+1<y.length?(a=(h+v+1)%y.length,T(k.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+y[a]+i})),v+=1):(d=g=!0,o=k,c=(p=function(){var e,t={},n=l.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][S]()]=o[1])}return t[b]||(e=(n=t.endpointsuffix)?t.location:null,t[b]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||l.instrumentationKey||"",p=(p=p[b])?p+"/v2/track":l.endpointUrl,(u=[]).push((t="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",n=o,r=p,(s=(i=m(c,"Exception")).data).baseType="ExceptionData",s.baseData.exceptions=[{typeName:"SDKLoadFailed",message:t.replace(/\./g,"-"),hasFullStack:!1,stack:t+"\nSnippet failed to load ["+n+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(w&&w.pathname||"_unknown_")+"\nEndpoint: "+r,parsedStack:[]}],i)),u.push((s=o,t=p,(r=(n=m(c,"Message")).data).baseType="MessageData",(i=r.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+s+")").replace(/\"/g,"")+'"',i.properties={endpoint:t},n)),o=u,c=p,JSON&&((r=C.fetch)&&!cfg.useXhr?r(c,{method:D,body:JSON.stringify(o),mode:"cors"}):XMLHttpRequest&&((s=new XMLHttpRequest).open(D,c),s.setRequestHeader("Content-type","application/json"),s.send(JSON.stringify(o))))))},a=function(e,t){g||setTimeout(function(){!t&&f.core||i()},500),d=!1},T=function(e){var n=x.createElement(I),e=(n.src=e,cfg[u]);return!e&&""!==e||"undefined"==n[u]||(n[u]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?x.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){x.getElementsByTagName(I)[0].parentNode.appendChild(n)},cfg.ld||0),n};T(k)}try{f.cookie=x.cookie}catch(p){}function t(e){for(;e.length;)!function(t){f[t]=function(){var e=arguments;d||f.queue.push(function(){f[t].apply(f,e)})}}(e.pop())}var r,s,n="track",o="TrackPage",c="TrackEvent",n=(t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+o,"stop"+o,"start"+c,"stop"+c,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),f.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(l.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==l[E]&&!0!==n[E]&&(t(["_"+(r="onerror")]),s=C[r],C[r]=function(e,t,n,i,a){var o=s&&s(e,t,n,i,a);return!0!==o&&f["_"+r]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},l.autoExceptionInstrumented=!0),f}(cfg.cfg),(C[n]=i).queue&&0===i.queue.length?(i.queue.push(e),i.trackPageView({})):e();})({
src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
// name: "appInsights",
// ld: 0,
// useXhr: 1,
crossOrigin: "anonymous",
// onInit: null,
// cr: 0,
cfg: { // Application Insights Configuration
 connectionString: "YOUR_CONNECTION_STRING"
}});
</script>

  2. (اختياري) قم بإضافة أو تحديث تكوين البرنامج النصي الاختياري JavaScript (Web) SDK Loader، اعتمادا على ما إذا كنت بحاجة إلى تحسين تحميل صفحة الويب الخاصة بك أو حل أخطاء التحميل.

    Screenshot of the JavaScript (Web) SDK Loader Script. The parameters for configuring the JavaScript (Web) SDK Loader Script are highlighted.

تكوين برنامج JavaScript (Web) SDK Loader Script

Name نوع مطلوب؟ ‏‏الوصف
src سلسلة المطلوب عنوان URL الكامل حيث يتم تحميل SDK منه. يتم استخدام هذه القيمة للسمة "src" لعلامة <البرنامج النصي/> المُضافة ديناميكياً. يمكنك استخدام موقع CDN العام أو موقعك الخاص المستضاف بشكل خاص.
الاسم سلسلة اختياري الاسم العمومي ل SDK التي تمت تهيئتها. استخدم هذا الإعداد إذا كنت بحاجة إلى تهيئة عددين مختلفين من SDK في نفس الوقت.

القيمة الافتراضية هي appInsights، لذلك window.appInsights هي مرجع إلى المثيل الذي تمت تهيئته.

ملاحظة: إذا قمت بتعيين قيمة اسم أو إذا تم تعيين مثيل سابق إلى الاسم العمومي appInsightsSDK، فإن التعليمة البرمجية لتهيئة SDK تتطلب أن تكون في مساحة الاسم العمومية window.appInsightsSDK=<name value> لضمان هيكل JavaScript (Web) SDK Loader Script الصحيح، ويتم تهيئة أساليب الوكيل وتحديثها.
ld الرقم بالملي ثانية اختياري قم بتعريف تأخير التحميل للانتظار قبل محاولة تحميل SDK. استخدم هذا الإعداد عندما تفشل صفحة HTML في التحميل لأن برنامج JavaScript (Web) SDK Loader Script يتم تحميله في الوقت الخطأ.

القيمة الافتراضية هي 0ms بعد انتهاء المهلة. إذا كنت تستخدم قيمة سالبة، تتم إضافة علامة البرنامج النصي على الفور إلى <head> منطقة الصفحة وتحظر حدث تحميل الصفحة حتى يتم تحميل البرنامج النصي أو فشله.
useXhr boolean اختياري يتم استخدام هذا الإعداد فقط للإبلاغ عن فشل تحميل عدة تطوير البرامج SDK. على سبيل المثال، يكون هذا الإعداد مفيدا عندما يقوم برنامج JavaScript (Web) SDK Loader Script بمنع تحميل صفحة HTML، مما يتسبب في عدم توفر الجلب().

يحاول إعداد التقارير أولا استخدام fetch() إذا كان متوفرا ثم الرجوع إلى XHR. قم بتعيين هذا الإعداد لتجاوز true التحقق من الإحضار. هذا الإعداد مطلوب فقط إذا كان التطبيق الخاص بك قيد الاستخدام في بيئة حيث قد تفشل عملية الجلب في إرسال أحداث الفشل مثل إذا لم يتم تحميل برنامج JavaScript (Web) SDK Loader Script بنجاح.
crossOrigin سلسلة اختياري من خلال تضمين هذا الإعداد، تتضمن علامة البرنامج النصي المضافة لتنزيل SDK السمة crossOrigin مع قيمة السلسلة هذه. استخدم هذا الإعداد عندما تحتاج إلى توفير الدعم ل CORS. عندما لا يتم تعريفه (الافتراضي)، لا يتم إضافة سمة crossOrigin. لا يتم تعريف القيم الموصى بها (الافتراضية) أو "" أو "المجهولة". للحصول على كافة القيم الصالحة، راجع وثائق سمة HTML عبر الأصل.
onInit function(aiSdk) { ... } اختياري يتم استدعاء دالة رد الاتصال هذه بعد تحميل البرنامج النصي SDK الرئيسي بنجاح وتهيئته من CDN (استنادا إلى قيمة src). تعد دالة رد الاتصال هذه مفيدة عندما تحتاج إلى إدراج مهيئ بيانات تتبع الاستخدام. يتم تمرير وسيطة واحدة، وهي مرجع إلى مثيل SDK الذي يتم استدعاؤه ويتم استدعاؤه أيضا قبل طريقة عرض الصفحة الأولية الأولى. إذا تم تحميل SDK وتهيئته بالفعل، فلا يزال يتم استدعاء رد الاتصال هذا. ملاحظة: أثناء معالجة صفيف sdk.queue، يتم استدعاء رد الاتصال هذا. لا يمكنك إضافة أي عناصر أخرى إلى قائمة الانتظار لأنه يتم تجاهلها وإسقاطها. (تمت إضافته كجزء من JavaScript (Web) SDK Loader Script الإصدار 5--القيمة sv:"5" داخل البرنامج النصي).
Cr boolean اختياري إذا فشل تحميل SDK وكانت قيمة نقطة النهاية المحددة لموقع src CDN العام، يحاول خيار التكوين هذا تحميل SDK على الفور من إحدى نقاط نهاية CDN الاحتياطية التالية:
  • .ingest.monitor.azure.com
  • js.cdn.applicationinsights.io
  • js.cdn.monitor.azure.com
  • js0.cdn.applicationinsights.io
  • js0.cdn.monitor.azure.com
  • js2.cdn.applicationinsights.io
  • js2.cdn.monitor.azure.com
  • az416426.vo.msecnd.net
ملاحظة: يتم دعم az416426.vo.msecnd.net جزئيا، لذلك لا يوصى به.

إذا تم تحميل SDK بنجاح من نقطة نهاية CDN احتياطية، فإنه يتم تحميله من أول نقطة متوفرة، والتي يتم تحديدها عندما يقوم الخادم بإجراء فحص تحميل ناجح. إذا فشل تحميل SDK من أي من نقاط نهاية CDN الاحتياطية، تظهر رسالة الخطأ فشل SDK.

عندما لا يتم تعريفها، تكون القيمة الافتراضية هي true. إذا كنت لا تريد تحميل SDK من نقاط نهاية CDN الاحتياطية، فقم بتعيين خيار التكوين هذا إلى false.

إذا كنت تقوم بتحميل SDK من نقطة نهاية CDN المستضافة بشكل خاص، فإن خيار التكوين هذا غير قابل للتطبيق.

لصق سلسلة الاتصال في بيئتك

للصق سلسلة الاتصال في بيئتك، اتبع الخطوات التالية:

  1. انتقل إلى جزء Overview لمورد Application Insights.

  2. حدد موقع سلسلة الاتصال ion.

  3. حدد أيقونة نسخ إلى الحافظة لنسخ سلسلة الاتصال إلى الحافظة.

    Screenshot that shows Application Insights overview and connection string.

  4. استبدل العنصر النائب "YOUR_CONNECTION_STRING" في تعليمة JavaScript البرمجية سلسلة الاتصال نسخها إلى الحافظة.

    connectionString يجب أن يتبع التنسيق "InstrumentationKey=xxxx;....". إذا كانت السلسلة المتوفرة لا تفي بهذا التنسيق، تفشل عملية تحميل SDK.

    لا يعتبر سلسلة الاتصال رمزا مميزا للأمان أو مفتاحا. لمزيد من المعلومات، راجع هل تتطلب مناطق Azure الجديدة استخدام سلسلة الاتصال؟.

(اختياري) إضافة تكوين SDK

يتم تمرير تكوين SDK الاختياري إلى Application Insights JavaScript SDK أثناء التهيئة.

لإضافة تكوين SDK، أضف كل خيار تكوين مباشرة ضمن connectionString. على سبيل المثال:

Screenshot of JavaScript code with SDK configuration options added and highlighted.

(اختياري) إضافة تكوين SDK متقدم

إذا كنت ترغب في استخدام الميزات الإضافية التي توفرها المكونات الإضافية لأطر عمل معينة وتمكين المكون الإضافي Click Analytics اختياريا، راجع:

تأكيد أن البيانات تتدفق

  1. انتقل إلى مورد Application Insights الذي قمت بتمكين SDK له.

  2. في قائمة مورد Application Insights على اليسار، ضمن Investigate، حدد جزء Transaction search.

  3. افتح القائمة المنسدلة أنواع الأحداث وحدد تحديد الكل لمسح خانات الاختيار في القائمة.

  4. من القائمة المنسدلة أنواع الأحداث، حدد:

    • عرض الصفحة ل Azure Monitor Application Insights Real User Monitoring
    • حدث مخصص للمكون الإضافي Click Analytics Auto-Collection.

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

    في بعض الحالات، إذا كانت مثيلات متعددة من إصدارات مختلفة من Application Insights تعمل على نفس الصفحة، يمكن أن تحدث أخطاء أثناء التهيئة. لهذه الحالات ورسالة الخطأ التي تظهر، راجع تشغيل إصدارات متعددة من Application Insights JavaScript SDK في جلسة عمل واحدة. إذا واجهت أحد هذه الأخطاء، فحاول تغيير مساحة الاسم باستخدام name الإعداد . لمزيد من المعلومات، راجع تكوين برنامج JavaScript (Web) SDK Loader Script.

    Screenshot of the Application Insights Transaction search pane in the Azure portal with the Page View option selected. The page views are highlighted.

  5. إذا كنت تريد الاستعلام عن البيانات لتأكيد تدفق البيانات:

    1. حدد Logs في الجزء الأيمن.

      عند تحديد Logs، يفتح مربع الحوار Queries، والذي يحتوي على عينة من الاستعلامات ذات الصلة ببياناتك.

    2. حدد تشغيل لنموذج الاستعلام الذي تريد تشغيله.

    3. إذا لزم الأمر، يمكنك تحديث نموذج الاستعلام أو كتابة استعلام جديد باستخدام Kusto Query Language (KQL).

      بالنسبة لمشغلي KQL الأساسيين، راجع التعرف على عوامل تشغيل KQL الشائعة.

الأسئلة الشائعة

يقدم هذا القسم إجابات للأسئلة الشائعة.

ما عدد المستخدمين وجلسات العمل؟

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

ما هو أداء/حمل JavaScript SDK؟

يحتوي Application Insights JavaScript SDK على الحد الأدنى من النفقات العامة على موقع الويب الخاص بك. في 36 كيلوبايت فقط gzipped، وأخذ فقط ~15 مللي ثانية للتهيئة، يضيف SDK مقدارا ضئيلا من وقت التحميل إلى موقع الويب الخاص بك. يتم تحميل الحد الأدنى من مكونات المكتبة بسرعة عند استخدام SDK، ويتم تنزيل البرنامج النصي الكامل في الخلفية.

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

ما هي المستعرضات التي يدعمها JavaScript SDK؟

Chrome Firefox IE Opera Safari
Chrome أحدث ✔ Firefox أحدث ✔ v3.x: IE 9+ وMicrosoft Edge ✔
v2.x: IE 8+ Compatible وMicrosoft Edge ✔		 Opera أحدث ✔ Safari أحدث ✔

أين يمكنني العثور على أمثلة التعليمات البرمجية ل JavaScript SDK؟

للحصول على أمثلة قابلة للتنفيذ، راجع عينات Application Insights JavaScript SDK.

ما هو توافق ES3/Internet Explorer 8 مع JavaScript SDK؟

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

لا يعني هذا البيان أننا ندعم فقط أقل مجموعة شائعة من الميزات. نحن بحاجة إلى الحفاظ على توافق التعليمة البرمجية ES3. يجب إضافة ميزات جديدة بطريقة لا تؤدي إلى تعطيل تحليل ES3 JavaScript وإضافتها كميزة اختيارية.

راجع GitHub للحصول على تفاصيل كاملة حول دعم Internet Explorer 8.

هل JavaScript SDK مفتوح المصدر؟

نعم، يتم مصدر مفتوح Application Insights JavaScript SDK. لعرض التعليمة البرمجية المصدرية أو للمساهمة في المشروع، راجع مستودع GitHub الرسمي.

يدعم

  • إذا لم تتمكن من تشغيل التطبيق أو لم تحصل على البيانات كما هو متوقع، فراجع مقالة استكشاف الأخطاء وإصلاحها المخصصة.
  • للسؤال الشائع حول JavaScript SDK، راجع الأسئلة المتداولة.
  • بالنسبة إلى مشكلات دعم Azure، افتح تذكرة دعم Azure.
  • للحصول على قائمة بالمشكلات المفتوحة المتعلقة ب Application Insights JavaScript SDK، راجع صفحة مشكلات GitHub.
  • استخدم ملحق عارض بيانات تتبع الاستخدام لسرد الأحداث الفردية في حمولة الشبكة ومراقبة المكالمات الداخلية داخل Application Insights.

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