واجهة برمجة تطبيقات Application Insights للأحداث والمقاييس المخصصة

مقالة
01/31/2024

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

إشعار

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

API summary

API الأساسية موحدة عبر جميع المنصات، وبصرف النظر عن بعض الاختلافات مثل GetMetric (.NET فقط).

الأسلوب	يُستخدم في
`TrackPageView`	الصفحات أو الشاشات أو الأجزاء أو النماذج.
`TrackEvent`	إجراءات المستخدم والأحداث الأخرى. تُستخدم لتعقب سلوك المستخدم أو لمراقبة الأداء.
`GetMetric`	المقاييس الصفرية ومتعددة الأبعاد، التجميع المكون مركزيًا، C# فقط.
`TrackMetric`	قياسات الأداء مثل أطوال قوائم الانتظار غير المرتبطة بأحداث معينة.
`TrackException`	تسجيل استثناءات التشخيص. تتبع مكان حدوثها فيما يتعلق بأحداث أخرى وفحص تتبعات المكدس.
`TrackRequest`	تسجيل تكرار ومدة طلبات الخادم ومدتها لتحليل الأداء.
`TrackTrace`	رسائل سجل تشخيص الموارد. يمكنك أيضاً تسجيل سجلات الجهات الخارجية.
`TrackDependency`	تسجيل مدة المكالمات وتكرارها إلى المكونات الخارجية التي يعتمد عليها تطبيقك.

يمكنك إرفاق خصائص ومقاييس بمعظم استدعاءات بيانات تتبع الاستخدام هذه.

قبل أن تبدأ

إذا لم يكن لديك مرجع على عدة تطوير البرامج لـ Application Insights حتى الآن:

أضف عدة تطوير البرامج لـ Application Insights لمشروع:
في التعليمات البرمجية بجهازك أو خادم الويب، بما يشمل:

C#‎:using Microsoft.ApplicationInsights;

Visual Basic:Imports Microsoft.ApplicationInsights

Java:import com.microsoft.applicationinsights.TelemetryClient;

Node.js:var applicationInsights = require("applicationinsights");

احصل على مثيل TelemetryClient

احصل على مثيل TelemetryClient (باستثناء مثيلات JavaScript في صفحات الويب):

بالنسبة لتطبيقات ASP.NET Core وNon-HTTP/Worker لـ .NET/.NET Core، احصل على مثيل TelemetryClient من حاوية حقن التبعية كما هو موضح في الوثائق الخاصة بكل منها.

إذا كنت تستخدم Azure Functions v2+ أو Azure WebJobs v3+، فقم بمشاهدة Monitor Azure Functions.

C#‎

private TelemetryClient telemetry = new TelemetryClient();

إذا رأيت رسالة تخبرك بأن هذا الأسلوب قديم، فقم بمشاهدة microsoft/ApplicationInsights-dotnet#1152 لمزيد من المعلومات.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient هو عبارة عن مؤشر ترابط آمن.

بالنسبة لمشروعات ASP.NET وJava، يتم التقاط طلبات HTTP الواردة تلقائيًا. ترغب في إنشاء المزيد من مثيلات TelemetryClient للوحدات النمطية الأخرى للتطبيق الخاص بك. على سبيل المثال، قد يكون لديك مثيل TelemetryClient واحد في فئة البرامج الوسيطة للإبلاغ عن أحداث منطق الأعمال. يمكنك تعيين خصائص مثلUserId وDeviceId للتعرف على الجهاز. يتم إرفاق هذه المعلومات إلى جميع الأحداث التي يرسلها المثيل.

C#‎

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

في مشاريع Node.js، يمكنك استخدام new applicationInsights.TelemetryClient(instrumentationKey?) لإنشاء مثيل جديد. نوصي بهذا الأسلوب فقط للسيناريوهات التي تحتاج إلى تكوينًا معزولًا من المفرد defaultClient.

TrackEvent

في Application Insights، الحدث المخصص هو نقطة بيانات التي يمكنك عرضها في Metrics Explorer كعدد مجمع، وفي Diagnostic Search كحوادث فردية. (لا علاقة للأمر بـ MVC أو غيره من أطر العمل "الأحداث").

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

على سبيل المثال، في تطبيق ألعاب، أرسل حدثاً كلما فاز مستخدم في اللعبة:

جافا سكريبت

appInsights.trackEvent({name:"WinGame"});

C#‎

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

أحداث مخصصة في Log Analytics

يتوفر القياس عن بُعد فيcustomEvents الجدول في علامة التبويب Application Insights Logs أو تجربة الاستخدام. قد تأتي الأحداث من trackEvent(..) أو البرنامج الإضافي Click Analytics Auto-collection.

إذا كان أخذ العينات قيد التشغيل، فإن الخاصية itemCount تعرض قيمة أكبر من 1. على سبيل المثال، itemCount==10 يعني أنه من بين 10 اتصالات إلى trackEvent()، نقلت عملية أخذ العينات واحدة منها فقط. للحصول على العدد الصحيح للأحداث المخصصة، استخدم رمزًا مثلcustomEvents | summarize sum(itemCount).

إشعار

itemCount له قيمة دنيا واحدة؛ السجل نفسه يمثل إدخالاً.

GetMetric

لمعرفة كيفية استخدام الاستدعاء GetMetric() بشكل فعال لالتقاط مقاييس مجمعة مسبقًا محليًا لتطبيقات .NET و.NET Core، راجع مجموعة المقاييس المخصصة في .NET و.NET Core.

TrackMetric

إشعار

Microsoft.ApplicationInsights.TelemetryClient.TrackMetricليست الطريقة المفضلة لإرسال المقاييس. يجب أن تكون المقاييس مجمعة مسبقاً خلال فترة زمنية قبل إرسالها. استخدم أحد الأحمال GetMetric(..) الزائدة للحصول على كائن متري للوصول إلى إمكانات التجميع المسبق لـ SDK.

إذا كنت تقوم بتطبيق منطق ما قبل التجميع الخاص بك، يمكنك استخدام الطريقة TrackMetric() لإرسال المجاميع الناتجة. إذا كان تطبيقك يتطلب إرسال عنصر قياس عن بُعد منفصل في كل مناسبة دون تجميع عبر الوقت، فمن المحتمل أن يكون لديك حالة استخدام للقياس عن بُعد للحدث. راجع TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

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

لإرسال المقاييس إلى Application Insights، يمكنك استخدام واجهة برمجة تطبيقات TrackMetric(..). هناك طريقتان لإرسال المقاييس:

القيمة الفردية. في كل مرة تجري فيها قياساً في التطبيق، ترسل القيمة المقابلة إلى Application Insights.

على سبيل المثال، افترض أن لديك مقياسًا يصف عدد العناصر في الحاوية. أثناء فترة زمنية معينة، وضعت أولاً ثلاثة عناصر في الحاوية ثم أزلت عنصرين. تبعًا لذلك، يمكنك استدعاء TrackMetric مرتين. أولاً، يمكنك تمرير القيمة 3 ثم تمرير القيمة -2. Application Insights يخزن كلا القيمتين بالنيابة عنك.
التجميع. عندما تعمل باستخدام المقاييس، نادرًا ما يكون كل مقياس منفردًا ذا أهمية. بدلاً من ذلك، من المهم تلخيص ما حدث خلال فترة زمنية معينة. هذا المخلص يسمى تجميعاً.

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

أمثلة ذات قيمة واحدة

لإرسال قيمة مقياس واحدة:

جافا سكريبت

appInsights.trackMetric({name: "queueLength", average: 42});

C#‎

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

المقاييس المخصصة في تحليلات السجل

بيانات تتبع الاستخدام متوفرة في customMetrics الجدول في تحليلات Application Insights. يمثل كل صف استدعاءً إلى trackMetric(..) في التطبيق.

valueSum: المجموع الخاص بالقياسات. للحصول على القيمة المتوسطة، اقسم على valueCount.
valueCount: عدد القياسات التي تم تجميعها في هذا الاستدعاء trackMetric(..).

إشعار

قيمة valueCount هي واحد كحد أدنى؛ السجل نفسه يمثل إدخالاً.

عرض الصفحة

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

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

مرات عرض الصفحة المخصصة

جافا سكريبت

appInsights.trackPageView("tab1");

C#‎

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

إذا كان لديك العديد من علامات التبويب ضمن صفحات HTML مختلفة، يمكنك تحديد عنوان URL أيضاً:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

توقيت عرض الصفحة

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

بدلاً من ذلك، يمكنك إما:

تعيين مدة صريحة في استدعاء TrackPageView:appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
استخدام استدعاءات توقيت عرض الصفحة startTrackPage وstopTrackPage.

جافا سكريبت

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

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

يتم اشتقاق مدة تحميل الصفحة الناتجة المعروضة في "مستكشف المقاييس" من الفاصل الزمني بين استدعاءات البدء والتوقف. الأمر متروك لك بشأن الفاصل الزمني الذي تحدد وقته.

قياس الصفحة عن بعد في تحليلات السجل

في Log Analytics، يعرض جدولان بيانات من عمليات المستعرض:

pageViews: يحتوي على بيانات حول عنوان URL وعنوان الصفحة.
browserTimings: يحتوي على بيانات حول أداء العميل مثل الوقت المستغرق لمعالجة البيانات الواردة.

للعثور على المدة التي يستغرقها المستعرض لمعالجة صفحات مختلفة:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

لاكتشاف مدى شعبية المتصفحات المختلفة:

pageViews
| summarize count() by client_Browser

لإقران عرض الصفحات لاستدعاءات AJAX، انضم إلى التبعيات:

pageViews
| join (dependencies) on operation_Id

TrackRequest

يستخدم الخادم SDK TrackRequest لتسجيل طلبات HTTP.

يمكنك أيضاً تسميته بنفسك إذا كنت ترغب في محاكاة الطلبات في سياق حيث لا يكون لديك وحدة خدمة الويب قيد التشغيل.

الطريقة الموصى بها لإرسال طلب القياس عن بعد هي المكان الذي يعمل فيه الطلب كسياق عملية.

سياق العملية

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

لمزيد من المعلومات حول الارتباط، راجع ارتباط القياس عن بُعد في Application Insights.

عندما تقوم بتتبع القياس عن بعد يدويًا، فإن أسهل طريقة لضمان ارتباط القياس عن بُعد هي باستخدام هذا النمط:

C#‎

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

إلى جانب تعيين سياق عملية، StartOperation ينشئ عنصر بيانات تتبع الاستخدام من النوع الذي تحدده. يرسل عنصر القياس عن بُعد عندما تتخلص من العملية أو إذا استدعيت صراحةً StopOperation. إذا كنت تستخدم RequestTelemetry كنوع بيانات تتبع الاستخدام، يتم تعيين مدته إلى الفاصل الزمني المؤقت بين البدء والتوقف.

تصبح عناصر القياس عن بعد التي يتم الإبلاغ عنها ضمن نطاق العملية أطفالًا لمثل هذه العملية. يمكن تداخل سياقات العملية.

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

لمزيد من المعلومات حول تعقب العمليات المخصصة، راجع تعقب العمليات المخصصة باستخدام Application Insights .NET SDK.

الطلبات فيما يتعلق بـ Log Analytics

في تحليلات Application Insights، تظهر الطلبات في جدول requests.

إذا كان أخذ العينات قيد التشغيل، فإن الخاصية itemCount تعرض قيمة أكبر من 1. على سبيل المثال، itemCount==10 يعني أنه من بين 10 اتصالات إلى trackRequest()، نقلت عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من الطلبات ومتوسط المدة مقسمة حسب أسماء الطلبات، استخدم التعليمة البرمجية مثل:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

أرسل استثناءات إلى Application Insights:

لحسابها، كمؤشر لتكرار المشكلة.
لفحص التكرارات الفردية.

تتضمن التقارير تتبعات المكدس.

C#‎

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Java

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

جافا سكريبت

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

تلتقط SDK العديد من الاستثناءات تلقائيًا، لذلك لا يتعين عليك دائمًا الاستدعاءTrackExceptionصراحةً:

ASP.NET: اكتب رمزًا لالتقاط الاستثناءات.
Java EE: يتم اكتشاف الاستثناءات تلقائيًا.
JavaScript: يتم اكتشاف الاستثناءات تلقائيًا. إذا كنت ترغب في تعطيل التجميع التلقائي، أضف سطرا إلى برنامج JavaScript (Web) SDK Loader Script الذي تقوم بإدراجه في صفحات الويب الخاصة بك:

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

استثناءات في تحليلات السجل

في تحليلات Application Insights، تظهر الاستثناءات في جدول exceptions.

إذا كان أخذ العينات قيد التشغيل، فإن الخاصية itemCount تعرض قيمة أكبر من 1. على سبيل المثال، itemCount==10 يعني أنه من بين 10 اتصالات إلى trackException()، نقلت عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من الاستثناءات مقسمة حسب نوع الاستثناء، استخدم التعليمة البرمجية مثل:

exceptions
| summarize sum(itemCount) by type

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

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

لربط الاستثناءات مع طلباتها ذات الصلة، استخدم صلة:

exceptions
| join (requests) on operation_Id

TrackTrace

قم باستخدام TrackTrace للمساعدة في تشخيص المشكلات عن طريق إرسال "مسار التنقل" إلى Application Insights. يمكنك إرسال مجموعات من البيانات التشخيصية وفحصها في "البحث التشخيصي".

في Log adapters .NET، استخدام API هذا لإرسال سجلات جهة خارجية إلى المدخل.

في Java، يقوم عامل Application Insights Javaتلقائيًا بتجميع السجلات وإرسالها إلى البوابة الإلكترونية.

C#‎

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Java

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Client/Browser-side JavaScript

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

سجل حدثاً تشخيصياً مثل إدخال أسلوب أو تركه.

المعلمة	‏‏الوصف‬
`message`	البيانات التشخيصية. يمكن أن يكون أطول بكثير من الاسم.
`properties`	تعيين السلسلة إلى السلسلة. يتم استخدام المزيد من البيانات من أجل تصفية الاستثناءات في المدخل. الإعدادات الافتراضية إلى فارغة.
`severityLevel`	القيم المدعُومَة: SeverityLevel.ts.

يمكنك البحث في محتوى الرسالة، ولكن على عكس قيم الخصائص، لا يمكنك التصفية عليها.

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

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

C#‎

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

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

تتبع في Log Analytics

في Application Insights Analytics، تظهر الاستدعاءاتTrackTraceفيtraces الجدول.

إذا كان أخذ العينات قيد التشغيل، فإن الخاصية itemCount تعرض قيمة أكبر من 1. على سبيل المثال، itemCount==10 يعني أنه من بين 10 اتصالات إلى trackTrace()، نقلت عملية أخذ العينات واحدة منها فقط. للحصول على العدد الصحيح لاستدعاءات التتبع، استخدم رمزًا مثل traces | summarize sum(itemCount).

TrackDependency

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

إشعار

بالنسبة لـ .NET و .NET Core، يمكنك بدلاً من ذلك استخدامTelemetryClient.StartOperation طريقة (extension) التي تملأDependencyTelemetry الخصائص المطلوبة للارتباط وبعض الخصائص الأخرى مثل وقت البدء والمدة، لذلك لا تحتاج إلى إنشاء مؤقت مخصص كما هو الحال مع الأمثلة التالية. لمزيد من المعلومات، قم بمراجعة القسم الخاص بتعقب التبعية الصادرة في تعقب العمليات المخصصة باستخدام Application Insights .NET SDK.

C#‎

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

تذكر أن عِدد SDK للخادم تتضمن وحدة نمطية تبعية التي تكتشف وتتعقب استدعاءات تبعية معينة تلقائياً--على سبيل المثال، إلى قواعد البيانات وREST APIs. يجب تثبيت عامل على خادمك لجعل الوحدة النمطية تعمل.

في Java، يمكن تتبع العديد من استدعاءات التبعية تلقائيًا باستخدام عامل Application Insights Java.

يمكنك استخدام هذا الاستدعاء إذا كنت تريد تعقب الاستدعاءات التي لا يسجلها التعقب التلقائي.

لإيقاف تشغيل الوحدة النمطية القياسية لتعقب التبعية بلغة C#، قم بتحرير ApplicationInsights.config وحذف المرجع إلى DependencyCollector.DependencyTrackingTelemetryModule. بالنسبة لـ Java، قم بمراجعةمنع بيانات تتبع استخدام محددة مجمعة تلقائيًا.

التبعيات في Log Analytics

فيما يتعلق بـ Application Insights Analytics، تظهر الاستدعاءات trackDependencyفي الجدول dependencies.

إذا كان أخذ العينات قيد التشغيل، تظهر الخاصية itemCount قيمة أكبر من 1. على سبيل المثال، itemCount==10 يعني أنه من بين 10 اتصالات إلى trackDependency()، نقلت عملية أخذ العينات واحدة منها فقط. للحصول على عدد صحيح من التبعيات مقسمة حسب المكون الهدف، استخدم التعليمات البرمجية مثل:

dependencies
| summarize sum(itemCount) by target

لربط التبعيات مع طلباتها ذات الصلة، استخدم صلة:

dependencies
| join (requests) on operation_Id

مسح البيانات

عادةً، ترسل SDK البيانات على فترات زمنية ثابتة، عادةً 30 ثانية، أو عندما يكون المخزن المؤقت ممتلئًا، والذي يكون عادةً 500 عنصر. في بعض الحالات، قد ترغب في مسح المخزن المؤقت. مثال على ذلك إذا كنت تستخدم SDK في تطبيق يتم إيقاف تشغيله.

NET.

بمجرد استخدام Flush()، نوصي بهذا النمط:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

عند استخدام FlushAsync()، نوصي بهذا النمط:

await telemetryClient.FlushAsync()
// No need to sleep

نوصي دائمًا بالتنظيف كجزء من إيقاف تشغيل التطبيق لضمان عدم فقد التتبع عن بُعد.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

الدالة غير متزامنة لقناة بيانات تتبع استخدام الخادم.

إشعار

يتم تدفق Java و JavaScript SDK تلقائيًا عند إيقاف تشغيل التطبيق.

المستخدمون المُصادقون

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

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

جافا سكريبت

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

في تطبيق MVC على الويب ASP.NET، على سبيل المثال:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

ليس من الضروري استخدام اسم تسجيل الدخول الفعلي للمستخدم. يجب فقط أن يكون معرف فريد من نوعه لهذا المستخدم. يجب ألا يتضمن مسافات أو أي من الأحرف ,;=|.

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

إذا كان تطبيقك يجمع المستخدمين في حسابات، يمكنك أيضًا تمرير معرّف للحساب. تَنطبق نفس قيود الأحرف.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

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

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

إشعار

تعمل خاصية EnableAuthenticationTrackingJavaScript في فئة ApplicationInsightsServiceOptions في .NET Core SDK على تبسيط تكوين JavaScript اللازم لإدخال اسم المستخدم باعتباره معرف المصادقة لكل تتبع يتم إرساله بواسطة Application Insights JavaScript SDK.

عند تعيين هذه الخاصية إلى true، تتم طباعة اسم المستخدم من المستخدم في ASP.NET Core جنبًا إلى جنب مع القياس عن بُعد من جانب العميل. لهذا السبب، لن تكون هناك حاجة إلى إضافة appInsights.setAuthenticatedUserContext يدويًا بعد الآن لأنه تم حقنه بالفعل بواسطة SDK ل ASP.NET Core. سيتم إرسال معرف Auth أيضًا إلى الخادم حيث يقوم SDK في .NET Core بتعريفه واستخدامه لأي بيانات تتبع استخدام من جانب الخادم، كما هو مبين في مرجع واجهة برمجة تطبيقات JavaScript.

بالنسبة لتطبيقات JavaScript التي لا تعمل بنفس طريقة ASP.NET Core MVC، مثل تطبيقات الويب SPA، فستظل بحاجة إلى إضافة appInsights.setAuthenticatedUserContext يدويًا.

تصفية البيانات والبحث فيها وتقسيمها باستخدام الخصائص

يمكنك إرفاق الخصائص والقياسات بالأحداث والمقاييس وعروض الصفحة والاستثناءات وبيانات القياس عن بُعد الأخرى.

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

قم بتحديد طول السلسلة هو 8,192. إذا كنت تريد إرسال أجزاء كبيرة من البيانات، فاستخدم معلمة الرسالة الخاصة بـ TrackTrace.

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

يجب أن تكون قيم القياس أكبر من أو تساوي 0 من أجل عرضها بشكل صحيح.

هناك بعض الحدود على عدد الخصائص وقيم الخصائص والمقاييس التي يمكنك استخدامها.

جافا سكريبت

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#‎

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

إشعار

قم بالتأكد من عدم تسجيل معلومات التعريف الشخصية في الخصائص.

طريقة بديلة لتعيين الخصائص والمقاييس

إذا كان أكثر ملاءمة، يمكنك جمع معلمات حدث ما في كائن منفصل:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

تحذير

لا تعيد استخدام نفس مثيل عنصر القياس عن بُعد (eventفي هذا المثال) للاستدعاء Track*()عدة مرات. قد تتسبب هذه الممارسة في إرسال القياس عن بُعد بتكوين غير صحيح.

قياسات وخصائص مخصصة في Log Analytics

في Log Analytics، تظهر المقاييس وcustomMeasurementsالخصائصcustomDimensionsالمخصصة في سمات كل سجل قياس عن بعد.

على سبيل المثال، إذا أضفت خاصية تسمى "game" إلى طلب التتبع عن بُعد الخاص بك، فإن هذا الاستعلام يحسب تكرارات القيم المختلفة لـ "game" ويعرض متوسط "نقاط" المقياس المخصص:

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

لاحظ أن:

عندما تستخرج قيمة منcustomDimensions JSON أوcustomMeasurements JSON، يكون لها نوع ديناميكي، لذلك يجب عليك إرسالها tostring أو todouble.
لمراعاة إمكانية أخذ العينات، استخدم sum(itemCount) وليس count().

أحداث التوقيت

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

C#‎

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

الخصائص الافتراضية لبيانات تتبع الاستخدام المخصصة

إذا كنت تريد تعيين قيم الخاصية الافتراضية لبعض الأحداث المخصصة التي تكتبها، فقم بتعيينها في مثيل TelemetryClient. إنها متصلة بكل عنصر تتبع عن بُعد يتم إرساله من ذلك العميل.

C#‎

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

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

لعملاء ويب JavaScript، استخدم مهايئات بيانات تتبع استخدام JavaScript.

لإضافة خصائص إلى جميع بيانات تتبع الاستخدام، بما في ذلك البيانات من الوحدات النمطية للمجموعات القياسية، قم بتنفيذ ITelemetryInitializer.

أخذ عينات وتصفية ومعالجة القياس عن بعد

راجع تصفية بيانات تتبع الاستخدام والمعالجة المسبقة في Application Insights SDK.

تعطيل بيانات تتبع الاستخدام

لبدء وإيقاف بشكل ديناميكي لجمع بيانات تتبع الاستخدام وإرسالها:

C#‎

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

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

Node.js

telemetry.config.disableAppInsights = true;

فيما يتعلق بتعطيل الجامعات القياسية المحددة--على سبيل المثال، عدادات الأداء، أو طلبات HTTP، أو التبعيات--في وقت البدء، تسلسل أساليب التكوين للتعليمة البرمجية لبدء SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

لتعطيل هذه الجامعات بعد التهيئة، قم باستخدام كائن التكوين: applicationInsights.Configuration.setAutoCollectRequests(false).

وضع المطوّر

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

C#‎

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

بالنسبة إلى Node.js، يمكنك تمكين وضع المطور من خلال تمكين التسجيل الداخلي عبر setInternalLogging والإعداد maxBatchSize إلى 0، ما يؤدي إلى إرسال بيانات التتبع عن بُعد بمجرد جمعها.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

قم بتعيين مفتاح الجهاز للقياس المخصص المحدد

C#‎

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

مفتاح الأجهزة الديناميكي

لتجنب خلط بيانات تتبع الاستخدام من بيئات التطوير والاختبار والإنتاج، يمكنك إنشاء موارد منفصلة في Application Insights وتغيير مفاتيحها، حسب البيئة.

بدلاً من الحصول على مفتاح تقرير عن حالة النظام من ملف التكوين، يمكنك تعيينه في التعليمة البرمجية. عيّن المفتاح في طريقة تهيئة، مثل global.aspx.cs في خدمة ASP.NET:

C#‎

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

جافا سكريبت

appInsights.config.instrumentationKey = myKey;

في صفحات الويب، قد ترغب في تعيينه من حالة خادم الويب بدلاً من ترميزه حرفيًا في البرنامج النصي. على سبيل المثال، في صفحة ويب تم إنشاؤها في تطبيق ASP.NET:

JavaScript في Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

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

telemetry.Context.Operation.Name = "MyOperationName";

إذا قمت بتعيين أي من هذه القيم بنفسك، ففكر في إزالة السطر ذي الصلة من ApplicationInsights.config حتى لا يتم الخلط بين قيمك والقيم القياسية.

المكون: التطبيق وإصداره.
الجهاز: بيانات حول الجهاز الذي يعمل فيه التطبيق. في تطبيقات الويب، يتم إرسال القياس عن بُعد من الخادم أو جهاز العميل.
InstrumentationKey: مورد Application Insights في Azure حيث يظهر بيانات تتبع الاستخدام. عادة ما يتم الاستعلام من ApplicationInsights.config.
الموقع: الموقع الجغرافي للجهاز.
العملية: في تطبيقات الويب، طلب HTTP الحالي. في أنواع التطبيقات الأخرى، يمكنك تعيين هذه القيمة لتجميع الأحداث معًا.
- ID: قيمة تم إنشاؤها ترتبط بأحداث مختلفة، بحيث يمكنك العثور على العناصر ذات الصلة عند فحص أي حدث في "البحث التشخيصي".
- الاسم: معرف، عادةً ما يكون عنوان URL لطلب HTTP.
- SyntheticSource: إذا لم يكن خالياً أو فارغاً، سلسلة تشير إلى أن مصدر الطلب قد تم تعريفه على أنه روبوت أو اختبار ويب. بشكل افتراضي، يتم استبعاده من العمليات الحسابية في Metrics Explorer.
جلسة العمل: جلسة عمل المستخدم. يتم تعيين المعرّف على قيمة تم إنشاؤها، والتي يتم تغييرها عندما لا يكون المستخدم نشطًا لفترة من الوقت.
المستخدم: معلومات المستخدم.

الحدود

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

Resource	الحد الافتراضي	الحد الأقصى	ملاحظات
إجمالي البيانات في اليوم	100 غيغابايت	اتصل بالدعم.	يمكنك تعيين حد أقصى لتقليل البيانات. إذا كنت بحاجة إلى مزيد من البيانات، فيمكنك زيادة الحد في المدخل حتى 1,000 جيجابايت. إذا كانت السعة أكبر من 1,000 جيجابايت، أرسل رسالة بريد إلكتروني إلى AIDataCap@microsoft.com.
التحكم بالنطاق الترددي*	32,000 حدث/ثانية	اتصل بالدعم.	يتم قياس الحد على مدى دقيقة.
سجلات استبقاء البيانات	من 30 إلى 730 يوما	730 يومًا	هذا المورد مخصص لـ السجلات.
مقاييس استبقاء البيانات	90 يومًا	90 يومًا	هذا المورد مخصص لـ مستكشف المقاييس.
توافر اختبار متعدد الخطوات الاستباق بالنتائج التفصيلية	90 يومًا	90 يومًا	يوفر هذا المورد نتائج مفصلة لكل خطوة.
الحد الأقصى لحجم عنصر القياس عن بعد	64 كيلو بايت	64 كيلو بايت
الحد الأقصى من عناصر القياس عن بعد لكل دفعة	64,000	64,000
طول اسم الموقع والمقياس	150	150	راجع مخططات الأنواع.
طول سلسلة قيمة الخاصية	8,192	8,192	راجع مخططات الأنواع.
طول رسالة التتبع والاستثناء	32,768	32,768	راجع مخططات الأنواع.
عدد اختبارات التوفر لكل مورد Application Insights	100	100
محلل ملفات التعريف واستبقاء بيانات اللقطة	أسبوعان	اتصل بفريق الدعم. حد الإستبقاء الأقصى هو 6 أشهر.
محلل ملفات التعريف البيانات المرسلة يوميًا	غير محدود	لا يوجد حد.
بيانات اللقطة المرسلة يوميًا	30 لقطة يوميًا لكل تطبيق مراقب	لا يوجد حد.	يمكن تعديل عدد اللقطات التي تم جمعها لكل تطبيق من خلال التكوين.

للحصول على مزيدٍ من المعلومات عن التسعير والحصص، راجع فواتير Application Insights.

لتجنب الوصول إلى حد معدل البيانات، استخدم أخذ العينات.

لتحديد المدة التي يتم فيها الاحتفاظ بالبيانات، راجع استبقاء البيانات والخصوصية.

وثائق مرجعية

تعليمة برمجية SDK

الأسئلة المتداولة

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

لماذا أفتقد بيانات تتبع الاستخدام؟

ستفقد كل من TelemetryChannels بيانات تتبع الاستخدام المخزنة مؤقتا إذا لم يتم مسحها قبل إيقاف تشغيل التطبيق.

لتجنب فقدان البيانات، قم بمسح TelemetryClient عند إيقاف تشغيل أحد التطبيقات.

لمزيد من المعلومات، راجع مسح البيانات.

ما الاستثناءات التي تلقيها استدعاءات `Track_()`؟

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

هل هناك REST API للحصول على البيانات من المدخل؟

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

لماذا يتم تجاهل مكالماتي إلى واجهات برمجة تطبيقات الأحداث والمقاييس المخصصة؟

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

قم بإيقاف تشغيل البنية التلقائية في مدخل Microsoft Azure على علامة التبويب Application Insights في صفحة App Service أو قم بتعيين ApplicationInsightsAgent_EXTENSION_VERSION إلى disabled.

لماذا تكون الأعداد في مخططات البحث والمقاييس غير متساوية؟

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

يحمل itemCount كل عنصر يتم إرساله خاصية توضح عدد الأحداث الأصلية التي يمثلها هذا العنصر. لمراقبة أخذ العينات في العملية، يمكنك تشغيل هذا الاستعلام في Log Analytics:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

كيف يمكنني ضبط تنبيه على حدث ما؟

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

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

البحث في الأحداث والسجلات

واجهة برمجة تطبيقات Application Insights للأحداث والمقاييس المخصصة

API summary

قبل أن تبدأ

احصل على مثيل TelemetryClient

TrackEvent

أحداث مخصصة في Log Analytics

GetMetric

TrackMetric

أمثلة ذات قيمة واحدة

المقاييس المخصصة في تحليلات السجل

عرض الصفحة

مرات عرض الصفحة المخصصة

توقيت عرض الصفحة

قياس الصفحة عن بعد في تحليلات السجل

TrackRequest

سياق العملية

الطلبات فيما يتعلق بـ Log Analytics

TrackException

استثناءات في تحليلات السجل

TrackTrace

تتبع في Log Analytics

TrackDependency

التبعيات في Log Analytics

مسح البيانات

المستخدمون المُصادقون

تصفية البيانات والبحث فيها وتقسيمها باستخدام الخصائص

طريقة بديلة لتعيين الخصائص والمقاييس

قياسات وخصائص مخصصة في Log Analytics

أحداث التوقيت

الخصائص الافتراضية لبيانات تتبع الاستخدام المخصصة

أخذ عينات وتصفية ومعالجة القياس عن بعد

تعطيل بيانات تتبع الاستخدام

وضع المطوّر

قم بتعيين مفتاح الجهاز للقياس المخصص المحدد

مفتاح الأجهزة الديناميكي

TelemetryContext

الحدود

وثائق مرجعية

تعليمة برمجية SDK

الأسئلة المتداولة

لماذا أفتقد بيانات تتبع الاستخدام؟

ما الاستثناءات التي تلقيها استدعاءات Track_()؟

هل هناك REST API للحصول على البيانات من المدخل؟

لماذا يتم تجاهل مكالماتي إلى واجهات برمجة تطبيقات الأحداث والمقاييس المخصصة؟

لماذا تكون الأعداد في مخططات البحث والمقاييس غير متساوية؟

كيف يمكنني ضبط تنبيه على حدث ما؟

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

الموارد الإضافية

ما الاستثناءات التي تلقيها استدعاءات `Track_()`؟