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

مشاركة عبر


مراقبة خدمات Node.js وتطبيقاته باستخدام Application Insights

يراقب Application Insights مكوّناتك بعد عملية التوزيع لاكتشاف الأداء والمشاكل الأخرى. يمكنك استخدام Application Insights لخدمات Node.js التي يتم استضافتها في مركز البيانات الخاص بك، وأجهزة Azure الظاهرية وتطبيقات الويب، وحتى في السحب العامة الأخرى.

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

يمكن لمكتبة عميل Node.js تلقائياً مراقبة طلبات HTTP الواردة والصادرة والاستثناءات وبعض قياسات النظام. بدءاً من الإصدار 0.20، يمكن لمكتبة العميل أيضاً مراقبة بعض حزم الجهات الخارجيةالشائعة، مثل MongoDB وMySQL وRedis.

ترتبط كافة الأحداث المتعلقة بطلب HTTP الوارد لاستكشاف الأخطاء وإصلاحها بشكل أسرع.

يمكنك استخدام واجهة برمجة تطبيقات TelemetryClient لوضع العلامات ومراقبة جوانب إضافية من التطبيق والنظام الخاص بك يدوياً. نصف واجهة برمجة تطبيقات TelemetryClient بمزيد من التفصيل لاحقًا في هذه المقالة.

تنبيه

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

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

أكمل المهام التالية لإعداد المراقبة لتطبيق أو خدمة.

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

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

إعداد مورد Application Insights

  1. قم بتسجيل الدخول إلى بوابة Azure.
  2. إنشاء مصدر Application Insights.

ملاحظة

في 31 مارس 2025، سينتهي دعم إدخال مفاتيح الأجهزة. سيستمر استيعاب مفتاح الأجهزة في العمل ولكننا لن نقوم بتوفير تحديثات أو أي دعم للميزة. الانتقال إلى سلاسل الاتصال للاستفادة من الإمكانات الجديدة.

إعداد مكتبة عميل Node.js

قم بتضمين SDK في تطبيقك حتى تتمكن من جمع البيانات.

  1. انسخ سلسلة اتصال المورد من المورد الجديد. يستخدم Application Insights سلسلة الاتصال لتعيين البيانات إلى مورد Azure. قبل أن يتمكن SDK من استخدام سلسلة الاتصال، يجب أن تحدد سلسلة الاتصال في متغيّر البيئة أو في التعليمات البرمجية.

    لقطة شاشة تعرض نظرة عامة حول Application Insights وسلسلة الاتصال.

  2. أضف مكتبة عميل Node.js إلى تبعيات تطبيقك عبر package.json. من المجلد الجذر لتطبيقك، قم بتشغيل:

    npm install applicationinsights --save
    

    ملاحظة

    إذا كنت تستخدم TypeScript، فلا تقم بتثبيت حزم "الكتابة" المنفصلة. تحتوي حزمة NPM هذه على كتابات مضمنة.

  3. قم بتحميل المكتبة في التعليمات البرمجية بشكل صريح. لأن SDK تدخل تقرير عن حالة النظام في العديد من المكتبات الأخرى، فقم بتحميل المكتبة في أقرب وقت ممكن، حتى قبل عبارات require الأخرى.

    let appInsights = require('applicationinsights');
    
  4. يمكنك أيضا توفير سلسلة الاتصال عبر متغير APPLICATIONINSIGHTS_CONNECTION_STRINGالبيئة ، بدلا من تمريره يدويا إلى setup() أو new appInsights.TelemetryClient(). تتيح لك هذه الممارسة الاحتفاظ بسلاسل الاتصال خارج التعليمات البرمجية المثبتة، ويمكنك تحديد سلاسل اتصال مختلفة لبيئات مختلفة. لإجراء تكويّناً يدوياً، يمكنك الاتصال بـ appInsights.setup('[your connection string]');.

    للحصول على خيارات تكوين إضافية، اطلع على المقاطع التالية.

    يمكنك تجربة SDK دون إرسال بيانات تتبع الاستخدام عن طريق تعيين appInsights.defaultClient.config.disableAppInsights = true.

  5. ابدأ تلقائيًا في جمع البيانات وإرسالها عن طريق استدعاء appInsights.start();.

ملاحظة

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

مراقبة التطبيق الخاص بك

تجمع SDK تلقائيًا بيانات تتبع الاستخدام حول وقت تشغيل Node.js وبعض الوحدات النمطية الشائعة لجهة خارجية. استخدم التطبيق لإنشاء بعض هذه البيانات.

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

لعرض المخطط الذي تم اكتشافه لتطبيقك، يمكنك استخدام مخطط التطبيق.

لا توجد بيانات

نظرا لأن SDK تجمع البيانات للإرسال، فقد يكون هناك تأخير قبل ظهور العناصر في المدخل. إذا لم تظهر البيانات في المورد، فجرّب بعض الإصلاحات التالية:

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

الاستخدام الأساسي

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


let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

ملاحظة

إذا تم تعيين سلسلة الاتصال في متغيّر البيئة APPLICATIONINSIGHTS_CONNECTION_STRING، .setup() يمكن استدعاؤها دون الحاجة إلى وسيطات. وذلك مما يسهل استخدام سلاسل اتصال مختلفة لبيئات مختلفة.

قم بتحميل مكتبة require("applicationinsights") Application Insights في أقرب وقت ممكن في البرامج النصية قبل تحميل حزم أخرى. هذه الخطوة مطلوبة بحيث يمكن لمكتبة Application Insights تحضير حزم لاحقة للتعقب. إذا واجهت تعارضات مع مكتبات أخرى تقوم بإعداد مماثل، فجرّب تحميل مكتبة Application Insights عقب ذلك مباشرة.

بسبب الطريقة التي يعالج بها JavaScript عمليات رد الاتصال، يلزم القيام بعمل إضافي لتعقب طلب عبر التبعيات الخارجية وعمليات رد الاتصال اللاحقة. بشكل افتراضي، يتم تمكين هذا التتبع الإضافي. قم بتعطيله عن طريق الاتصال setAutoDependencyCorrelation(false) كما هو موضح في قسم تكوين SDK.

الترحيل من الإصدارات السابقة ل 0.22

هناك تغييرات فاصلة بين الإصدارات قبل الإصدار 0.22 وما بعده. تم تصميم هذه التغييرات لتحقيق التناسق مع مجموعات Application Insights SDK وللسماح بالتوسع في المستقبل.

بشكل عام، يمكنك الترحيل بالإجراءات التالية:

  • استبدل المراجع appInsights.client بـ appInsights.defaultClient.
  • استبدل المراجع appInsights.getClient() بـ new appInsights.TelemetryClient().
  • استبدال كافة الوسيطات إلى أساليب client.track* مع كائن واحد يحتوي على خصائص محددة كوسيطات. راجع تلميح نوع IDE المضمن أو TelemetryTypes للكائن المستثنى لكل نوع من أنواع بيانات تتبع الاستخدام.

إذا قمت بالوصول إلى وظائف تكوين SDK دون ربطها ب appInsights.setup()، يمكنك الآن العثور على هذه الدالات في appInsights.Configurations. مثال على ذلك appInsights.Configuration.setAutoCollectDependencies(true) . راجع التغييرات على التكوين الافتراضي في المقطع التالي.

تكوين SDK

يوفر العنصر appInsights عدداً من أساليب التكوين. يتم سردها في القصاصة البرمجية التالية مع قيمها الافتراضية.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

لربط الأحداث بشكل كامل بخدمة، تأكد من تعيين .setAutoDependencyCorrelation(true). باستخدام مجموعة الخيارات هذه، يمكن لـ SDK تعقب السياق عبر الاسترجاعات غير المتزامنة في Node.js.

راجع أوصافها في تلميح النوع المضمن ل IDE أو applicationinsights.ts للحصول على معلومات مفصلة ووسيطات ثانوية اختيارية.

ملاحظة

بشكل افتراضي، setAutoCollectConsole يتم تكوين لاستبعاد الاستدعاءات إلى console.log وأساليب وحدة التحكم الأخرى. سيتم جمع استدعاءات مسجّلات الجهات الخارجية المدعومة (على سبيل المثال، winston وbunyan). يمكنك تغيير هذا السلوك لتضمين استدعاءات إلى أساليب console باستخدام setAutoCollectConsole(true, true).

أخذ عينات

بشكل افتراضي، يرسل SDK جميع البيانات المجمعة إلى خدمة Application Insights. إذا كنت ترغب في تمكين أخذ العينات لتقليل كمية البيانات، فقم بتعيين الحقل samplingPercentage على عنصر العميل config. يعني الإعداد samplingPercentage إلى 100 (الافتراضي) أنه سيتم إرسال جميع البيانات، و0 يعني أنه لن يتم إرسال أي شيء.

إذا كنت تستخدم الارتباط التلقائي، يتم تضمين جميع البيانات المقترنة بطلب واحد أو استبعادها كوحدة.

إضافة تعليمات برمجية مثل ما يلي لتمكين أخذ العينات:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

أدوار متعددة للتطبيقات متعددة المكونات

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

استخدم التعليمات البرمجية RoleName التالية لتعيين الحقل:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

محمل SDK للمستعرض

يمكن تمكين أدوات الويب التلقائية لخادم العقدة عبر حقن برنامج JavaScript (Web) SDK Loader Script عن طريق التكوين.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

أو عن طريق تعيين متغير APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = trueالبيئة .

يتم تمكين Web Instrumentation على استجابات خادم العقدة عند استيفاء جميع المتطلبات التالية:

  • الاستجابة لها رمز 200الحالة .
  • أسلوب الاستجابة هو GET.
  • استجابة الخادم لها Content-Type html.
  • تحتوي استجابة الخادم على كل من <head> و </head> العلامات.
  • إذا تم ضغط الاستجابة، يجب أن يكون لها نوع واحد Content-Encoding فقط، ويجب أن يكون نوع الترميز واحدا من gzip، br أو deflate.
  • لا تحتوي الاستجابة على نقاط نهاية CDN الحالية /الاحتياطية للأجهزة على الويب. (نقاط نهاية Web Instrumentation CDN الحالية والنسخ الاحتياطي هنا)

يمكن تغيير نقطة نهاية WEB Instrumentation CDN عن طريق تعيين متغير APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"البيئة . يمكن تغيير سلسلة الاتصال تقرير عن حالة النظام على الويب عن طريق تعيين متغير البيئةAPPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

ملاحظة

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

تقرير عن حالة النظام تلقائي لجهة خارجية

لتعقب السياق عبر المكالمات غير المتزامنة، يلزم إجراء بعض التغييرات في مكتبات الجهات الخارجية، مثل MongoDB وRedis. بشكل افتراضي، يستخدم diagnostic-channel-publishers Application Insights لتصحيح بعض هذه المكتبات. يمكن تعطيل هذه الميزة عن طريق تعيين متغيّر البيئة APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

ملاحظة

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

يمكن تعطيل تصحيحات الفردية عن طريق تعيين APPLICATION_INSIGHTS_NO_PATCH_MODULES متغير البيئة إلى قائمة مفصولة بفواصل من الحزم لتعطيلها. على سبيل المثال، استخدم APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis لتجنب تصحيح console الحزم و redis .

حاليا، يتم وضع علامة على تسع حزم: bunyanوconsole وmongodb وmongodb-core وmysql وredis وpgwinstonpg-pool. للحصول على معلومات حول إصدار هذه الحزم الذي تم تصحيحه بالضبط، راجع README الخاص ب ناشري القناة التشخيصية.

bunyanwinstonتقوم التصحيحات و و console بإنشاء أحداث تتبع Application Insights استنادا إلى ما إذا كان setAutoCollectConsole ممكنا أم لا. ينشئ الباقي أحداث تبعية Application Insights استنادا إلى ما إذا كان setAutoCollectDependencies ممكنا أم لا.

المقاييس الحية

لتمكين إرسال مقاييس مباشرة من تطبيقك إلى Azure، استخدم setSendLiveMetrics(true). حاليا، تصفية المقاييس المباشرة في المدخل غير مدعومة.

مقاييس ممتدة

ملاحظة

تمت إضافة القدرة على إرسال مقاييس أصلية موسعة في الإصدار 1.4.0.

لتمكين إرسال مقاييس أصلية ممتدة من تطبيقك إلى Azure، فقم بتثبيت حزمة المقاييس الأصلية المنفصلة. يتم تحميل SDK تلقائيا عند تثبيته وبدء جمع Node.js المقاييس الأصلية.

npm install applicationinsights-native-metrics

حاليًا، تنفذ حزمة المقاييس الأصلية التجميع التلقائي لوقت معالج تجميع البيانات المهملة، وعلامات تكرار حلقي للأحداث، واستخدام كومة الذاكرة المؤقتة:

  • Garbage collection: مقدار الوقت الذي يقضيه المعالج على كل نوع من أنواع تجميع البيانات المهملة وعدد مرات التواجد من كل نوع.
  • Event loop: عدد العلامات التي حدثت ومقدار الوقت الذي يقضيه المعالج إجمالًا.
  • كومة الذاكرة المؤقتة مقابل غير كومة الذاكرة المؤقتة: مقدار استخدام ذاكرة التطبيق في كومة الذاكرة المؤقتة أو غير كومة الذاكرة المؤقتة.

أوضاع التتبع الموزعة

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

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

واجهة برمجة تطبيقات TelemetryClient

للحصول على وصف كامل لواجهة برمجة تطبيقات TelemetryClient، راجع واجهة برمجة تطبيقات Application Insights للأحداث والمقاييس المخصصة.

يمكنك تعقب أي طلب أو حدث أو مقياس أو استثناء باستخدام مكتبة عميل Application Insights لـ Node.js. يوضح مثال التعليمات البرمجية التالي بعض واجهات برمجة التطبيقات التي يمكنك استخدامها فيما يلي:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

تتبع التبعيات الخاصة بك

استخدم التعليمات البرمجية التالية لتعقب التبعيات الخاصة بك:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

أداة مساعدة مثال تستخدم trackMetric لقياس المدة التي يستغرقها جدولة تكرار حلقي للحدث:

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

إضافة خاصية مخصصة إلى كافة الأحداث

استخدم التعليمات البرمجية التالية لإضافة خاصية مخصصة إلى كافة الأحداث:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

تتبع طلبات HTTP GET

استخدم التعليمات البرمجية التالية لتعقب طلبات HTTP GET يدويًا:

ملاحظة

  • يتم تعقب كافة الطلبات بشكل افتراضي. لتعطيل المجموعة التلقائية، اتصل .setAutoCollectRequests(false) قبل استدعاء start().
  • لا يتم تعقب طلبات واجهة برمجة تطبيقات الإحضار الأصلية تلقائيا بواسطة Application Insights الكلاسيكي؛ مطلوب تتبع التبعية اليدوية.
appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

بدلا من ذلك، يمكنك تعقب الطلبات باستخدام trackNodeHttpRequest الأسلوب :

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

تعقب وقت بدء تشغيل الخادم

استخدم التعليمات البرمجية التالية لتعقب وقت بدء تشغيل الخادم:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

المسح

بشكل افتراضي، يتم تخزين بيانات تتبع الاستخدام بشكل مؤقت لمدة 15 ثانية قبل إرسالها إلى خادم الاستيعاب. إذا كان التطبيق الخاص بك يحتوي على عمر قصير، مثل أداة CLI، فقد يكون من الضروري مسح بيانات تتبع الاستخدام المخزنة مؤقتا يدويا عند إنهاء التطبيق باستخدام appInsights.defaultClient.flush().

إذا اكتشف SDK أن التطبيق الخاص بك يتعطل، فإنه يستدعي تدفق لك باستخدام appInsights.defaultClient.flush({ isAppCrashing: true }). مع خيار isAppCrashingالمسح ، يفترض أن التطبيق الخاص بك في حالة غير طبيعية وغير مناسب لإرسال بيانات تتبع الاستخدام. بدلا من ذلك، يحفظ SDK جميع بيانات تتبع الاستخدام المخزنة مؤقتا إلى التخزين المستمر ويتيح إنهاء التطبيق الخاص بك. عند بدء تشغيل التطبيق الخاص بك مرة أخرى، فإنه يحاول إرسال أي بيانات تتبع الاستخدام التي تم حفظها في التخزين المستمر.

معالجة البيانات مسبقًا بمعالجات بيانات تتبع الاستخدام

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

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

إذا قام معالج بيانات تتبع الاستخدام بإرجاع false، فلن يتم إرسال عنصر بيانات تتبع الاستخدام هذا.

معالجات بيانات تتبع الاستخدام ستتلقى جميع بيانات تتبع الاستخدام ومغلفها لفحصها وتعديلها. كما أنها ستتلقى كائن سياق. يتم تعريف محتويات هذا الكائن بواسطة المعلمة contextObjects عند استدعاء أسلوب تعقب لبيانات تتبع الاستخدام المتعقبة يدويا. بالنسبة إلى بيانات تتبع الاستخدام الذي تم تجميعه تلقائيًا، يتم تعبئة هذا الكائن بمعلومات الطلب المتوفرة ومحتوى الطلب المستمر كما هو منصوص عليه appInsights.getCorrelationContext() (إذا تم تمكين ارتباط التبعية التلقائي).

نوع TypeScript لمعالج بيانات تتبع الاستخدام هو:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

على سبيل المثال، قد تتم كتابة معالج يزيل بيانات تتبع المكدسات من الاستثناءات وإضافتها كما يلي:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

استخدام سلاسل الاتصال المتعددة

يمكنك إنشاء موارد متعددة لدى Application Insights وإرسال بيانات مختلفة لكل منها باستخدام سلاسل اتصال مختصة بكل منها.

على سبيل المثال:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

خيارات التكوين المتقدمة

يحتوي عنصر العميل على خاصية config مع العديد من الإعدادات الاختيارية للسيناريوهات المتقدمة. لتعيينها، استخدم:

client.config.PROPERTYNAME = VALUE;

هذه الخصائص هي خاصة بالعميل، بحيث يمكنك تكوين appInsights.defaultClient بشكل منفصل عن العملاء الذين تم إنشاؤهم باستخدام new appInsights.TelemetryClient().

الخاصية ‏‏الوصف
سلسلة الاتصال معرف مورد Application Insights الخاص بك.
endpointUrl نقطة نهاية الاستيعاب لإرسال حمولات بيانات تتبع الاستخدام إليها.
quickPulseHost تنقل المقاييس المباشرة باستمرار المضيف لإرسال بيانات تتبع الاستخدام للمقاييس المباشرة إليها.
proxyHttpUrl خادم وكيل لحركة مرور SDK HTTP. (اختياري. يتم سحب الافتراضي من http_proxy متغير البيئة.)
proxyHttpsUrl خادم وكيل لحركة مرور SDK HTTPS. (اختياري. يتم سحب الافتراضي من https_proxy متغير البيئة.)
httpAgent http. عامل لاستخدامه لحركة مرور SDK HTTP. (اختياري. الافتراضي غير معرف.)
httpsAgent https. عامل لاستخدامه لحركة مرور SDK HTTPS. (اختياري. الافتراضي غير معرف.)
maxBatchSize الحد الأقصى لعدد عناصر بيانات تتبع الاستخدام المراد تضمينها في حمولة إلى نقطة نهاية الاستيعاب. (الافتراضي هو 250.)
maxBatchIntervalMs الحد الأقصى لمقدار الوقت للانتظار حتى تصل الحمولة إلى maxBatchSize. (الافتراضي هو 15000.)
disableAppInsights علامة تشير إلى ما إذا كان إرسال بيانات تتبع الاستخدام معطلا. (الافتراضي هو false.)
samplingPercentage النسبة المئوية لعناصر بيانات تتبع الاستخدام التي يجب إرسالها. (الافتراضي هو 100.)
correlationIdRetryIntervalMs وقت الانتظار قبل إعادة المحاولة لاسترداد معرف الارتباط عبر المكونات. (الافتراضي هو 30000.)
correlationHeaderExcludedDomains قائمة بالمجالات التي يجب استبعادها من حقن عنوان الارتباط عبر المكونات. (افتراضي. راجع Config.ts.)

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

كيف يمكنني تعطيل ارتباط بيانات تتبع الاستخدام؟

لتعطيل ارتباط بيانات تتبع الاستخدام، استخدم الخاصية correlationHeaderExcludedDomains في التكوين. لمزيد من المعلومات، راجع ApplicationInsights-node.js.

استكشاف الأخطاء وإصلاحها

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

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