تطبيقات Application Insights لخدمة العامل (تطبيقات بخلاف تطبيقات HTTP)

مقالة
01/31/2024

Application Insights SDK for Worker Service هو SDK جديد، وهو الأنسب لأحمال العمل غير HTTP مثل المراسلة والمهام الخلفية وتطبيقات وحدة التحكم. لا تحتوي هذه الأنواع من التطبيقات على فكرة طلب HTTP وارد مثل تطبيق ويب تقليدي ASP.NET/ASP.NET Core. لهذا السبب، استخدام حزم Application Insights للتطبيقات الأساسية ASP.NET أو ASP.NET غير مدعوم.

إشعار

تعتمد الوثائق التالية على واجهة برمجة تطبيقات Application Insights الكلاسيكية. الخطة طويلة الأجل ل Application Insights هي جمع البيانات باستخدام OpenTelemetry. لمزيد من المعلومات، راجع تمكين Azure Monitor OpenTelemetry لتطبيقات .NET Node.js وPython وJava.

لا يقوم SDK الجديد بأيّ مجموعة قياس عن بعد بمفرده. بدلا من ذلك، فإنه يجلب مجمعات تلقائية أخرى معروفة ل Application Insights مثل DependencyCollector و PerfCounterCollector و ApplicationInsightsLoggingProvider. يعرض SDK أساليب IServiceCollection الامتداد هذه لتمكين وتكوين مجموعة بيانات تتبع الاستخدام.

السيناريوهات المدعومة

يُعد Application Insights SDK لخدمة العامل هو الأنسب للتطبيقات بخلاف تطبيقات HTTP بغض النظر عن مكان أو كيفية تشغيلها. إذا كان التطبيق الخاص بك قيد التشغيل ولديه اتصال بالشبكة بـ Azure ، فيمكن جمع بيانات القياس عن بُعد. يتم دعم مراقبة Application Insights في كل مكان يتم دعم NET Core فيه. يمكن استخدام هذه الحزمة في خدمة .NET Core Worker التي تم تقديمها حديثا، ومهام الخلفية في ASP.NET Core، وتطبيقات وحدة التحكم مثل .NET Core و.NET Framework.

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

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

إشعار

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

استخدام Application Insights SDK لخدمة العامل

قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService إلى التطبيق. تعرض القصاصة البرمجية التالية التغييرات التي يجب إضافتها إلى ملف المشروع .csproj :
```
    <ItemGroup>
        <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    </ItemGroup>
```
تكوين سلسلة الاتصال في APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة أو في التكوين (appsettings.json).
استرداد مثيل ILogger أو TelemetryClient مثيل من حاوية إدخال التبعية (DI) عن طريق استدعاء serviceProvider.GetRequiredService<TelemetryClient>(); أو باستخدام حقن المنشئ. ستؤدي هذه الخطوة إلى تشغيل إعداد TelemetryConfiguration وحدات التجميع التلقائي.

يتم وصف إرشادات مُعينة لكل نوع من أنواع التطبيقات في الأقسام التالية.

تطبيق .NET Core Worker Service

تتم مشاركة المثال الكامل في موقع NuGet على الويب.

قم بتنزيل وتثبيت .NET SDK.
إنشاء مشروع خدمة عامل جديد إما باستخدام قالب مشروع Visual Studio جديد أو سطر dotnet new workerالأوامر .
أضف حزمة Microsoft.ApplicationInsights.WorkerService إلى التطبيق.

إضافة services.AddApplicationInsightsTelemetryWorkerService(); إلى الأسلوب في CreateHostBuilder()Program.cs الفئة الخاصة بك، كما في هذا المثال:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
                services.AddApplicationInsightsTelemetryWorkerService();
            });

تعديل وفقا Worker.cs للمثال التالي:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;
        private static HttpClient _httpClient = new HttpClient();

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
                {
                    _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                    _logger.LogInformation("Calling bing.com");
                    var res = await _httpClient.GetAsync("https://bing.com");
                    _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                    _telemetryClient.TrackEvent("Bing call event completed");
                }

                await Task.Delay(1000, stoppingToken);
            }
        }
    }

تثبيت سلسلة الاتصال.

إشعار

نوصي بتحديد سلسلة الاتصال في التكوين. يوضح نموذج التعليمات البرمجية التالي كيفية تحديد سلسلة اتصال في appsettings.json. تأكد من نسخهappsettings.json إلى المجلد الجذر للتطبيق أثناء النشر.
```
    {
        "ApplicationInsights":
        {
            "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
        },
        "Logging":
        {
            "LogLevel":
            {
                "Default": "Warning"
            }
        }
    }
```

بدلاً من ذلك، حدد سلسلة الاتصال في متغير البيئة APPLICATIONINSIGHTS_CONNECTION_STRING.

عادة ما APPLICATIONINSIGHTS_CONNECTION_STRING يحدد سلسلة الاتصال للتطبيقات المنشورة على تطبيقات الويب كمهام ويب.

إشعار

سلسلة الاتصال المُحددة في التعليمات البرمجية لها الأسبقية على متغير البيئة APPLICATIONINSIGHTS_CONNECTION_STRING، والذي له الأسبقية على الخيارات الأخرى.

مهام خلفية ASP.NET Core مع الخدمات المستضافة

يصف هذا المستند كيفية إنشاء مهام الخلفية في تطبيق ASP.NET Core.

تتم مشاركة المثال الكامل في صفحة GitHub هذه.

قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService إلى التطبيق.

أضف services.AddApplicationInsightsTelemetryWorkerService(); إلى الأسلوب ConfigureServices()، كما في هذا المثال:

    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .ConfigureAppConfiguration((hostContext, config) =>
            {
                config.AddJsonFile("appsettings.json", optional: true);
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddLogging();
                services.AddHostedService<TimedHostedService>();

                // connection string is read automatically from appsettings.json
                services.AddApplicationInsightsTelemetryWorkerService();
            })
            .UseConsoleLifetime()
            .Build();

        using (host)
        {
            // Start the host
            await host.StartAsync();

            // Wait for the host to shutdown
            await host.WaitForShutdownAsync();
        }
    }

التعليمات البرمجية التالية ل TimedHostedService، حيث يوجد منطق مهمة الخلفية:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class TimedHostedService : IHostedService, IDisposable
    {
        private readonly ILogger _logger;
        private Timer _timer;
        private TelemetryClient _telemetryClient;
        private static HttpClient httpClient = new HttpClient();

        public TimedHostedService(ILogger<TimedHostedService> logger, TelemetryClient tc)
        {
            _logger = logger;
            this._telemetryClient = tc;
        }

        public Task StartAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("Timed Background Service is starting.");

            _timer = new Timer(DoWork, null, TimeSpan.Zero,
                TimeSpan.FromSeconds(1));

            return Task.CompletedTask;
        }

        private void DoWork(object state)
        {
            _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

            using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
            {
                _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                _logger.LogInformation("Calling bing.com");
                var res = httpClient.GetAsync("https://bing.com").GetAwaiter().GetResult();
                _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                _telemetryClient.TrackEvent("Bing call event completed");
            }
        }
    }

تثبيت سلسلة الاتصال. استخدم نفس الشيء appsettings.json من مثال .NET Worker Service السابق.

تطبيق وحدة تحكم .NET Core/.NET Framework

كما هو مذكور في بداية هذه المقالة، يمكن استخدام الحزمة الجديدة لتمكين بيانات تتبع الاستخدام Application Insights حتى من تطبيق وحدة تحكم عادي. تستهدف هذه الحزمة netstandard2.0، بحيث يمكن استخدامها لتطبيقات وحدة التحكم في .NET Core أو أعلى، و.NET Framework أو أعلى.

تتم مشاركة المثال الكامل في صفحة GitHub هذه.

قم بتثبيت حزمة Microsoft.ApplicationInsights.WorkerService إلى التطبيق.

تعديل Program.cs كما هو موضح في المثال التالي:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;
    using Microsoft.ApplicationInsights.WorkerService;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Logging;
    using System;
    using System.Net.Http;
    using System.Threading.Tasks;

    namespace WorkerSDKOnConsole
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                // Create the DI container.
                IServiceCollection services = new ServiceCollection();

                // Being a regular console app, there is no appsettings.json or configuration providers enabled by default.
                // Hence instrumentation key/ connection string and any changes to default logging level must be specified here.
                services.AddLogging(loggingBuilder => loggingBuilder.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("Category", LogLevel.Information));
                services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = "InstrumentationKey=<instrumentation key here>");

                // To pass a connection string
                // - aiserviceoptions must be created
                // - set connectionstring on it
                // - pass it to AddApplicationInsightsTelemetryWorkerService()

                // Build ServiceProvider.
                IServiceProvider serviceProvider = services.BuildServiceProvider();

                // Obtain logger instance from DI.
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                // Obtain TelemetryClient instance from DI, for additional manual tracking or to flush.
                var telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

                var httpClient = new HttpClient();

                while (true) // This app runs indefinitely. Replace with actual application termination logic.
                {
                    logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                    // Replace with a name which makes sense for this operation.
                    using (telemetryClient.StartOperation<RequestTelemetry>("operation"))
                    {
                        logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                        logger.LogInformation("Calling bing.com");                    
                        var res = await httpClient.GetAsync("https://bing.com");
                        logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                        telemetryClient.TrackEvent("Bing call event completed");
                    }

                    await Task.Delay(1000);
                }

                // Explicitly call Flush() followed by sleep is required in console apps.
                // This is to ensure that even if application terminates, telemetry is sent to the back-end.
                telemetryClient.Flush();
                Task.Delay(5000).Wait();
            }
        }
    }

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

تشغيل التطبيق الخاص بك

قم بتشغيل تطبيقك. يقوم العمال من جميع الأمثلة السابقة بإجراء استدعاء HTTP كل ثانية إلى bing.com وأيضا إصدار سجلات قليلة باستخدام ILogger. يتم التفاف هذه الأسطر داخل StartOperation استدعاء TelemetryClient، والذي يستخدم لإنشاء عملية. في هذا المثال، RequestTelemetry يسمى "operation".

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

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

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

تسرد الأقسام التالية بيانات تتبع الاستخدام الكاملة التي تم جمعها تلقائيا بواسطة Application Insights.

القياسات المباشرة

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

سجلات ILogger

يتم التقاط السجلات المنبعثة عبر ILogger مع تحذير الخطورة أو أكبر تلقائيا. لتغيير هذا السلوك، تجاوز تكوين التسجيل للموفر ApplicationInsightsبشكل صريح، كما هو موضح في التعليمات البرمجية التالية. يسمح التكوين التالي لـ Application Insights بالتقاط جميع السجلاتInformationوالسجلات الأكثر خطورة.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

من المهم ملاحظة أن المثال التالي لا يتسبب في قيام موفر Application Insights بالتقاط Information السجلات. لا يتم التقاطها لأن SDK تضيف مرشح تسجيل افتراضيًا يرشدك إلىApplicationInsightsالتقاط السجلات فقطWarning وسجلات أكثر خطورة. يتطلب Application Insights تجاوزًا صريحًا.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

لمزيد من المعلومات، اتبع مستندات ILogger لتخصيص مستويات السجل التي يتم التقاطها بواسطة Application Insights.

التبعيات

يتم تمكين مجموعة التبعية بشكل افتراضي. تشرح المقالة تتبع التبعية في Application Insights التبعيات التي يتم جمعها تلقائيا وتحتوي أيضا على خطوات للقيام بالتتبع اليدوي.

EventCounter

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

تعقب بيانات تتبع الاستخدام الأخرى يدويا

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

قم بتكوين Application Insights SDK

الإعداد الافتراضي TelemetryConfiguration المستخدم من قبل Worker Service SDK مشابه للتكوين التلقائي المستخدم في تطبيق ASP.NET أو ASP.NET Core، مطروحا منه مهيئات بيانات تتبع الاستخدام المستخدمة لإثراء بيانات تتبع الاستخدام من HttpContext.

يمكنك تخصيص Application Insights SDK لخدمة العمال لتغيير التكوين الافتراضي. قد يكون مستخدمو Application Insights ASP.NET Core SDK على دراية بتغيير التكوين باستخدام إدخال التبعية المضمن في ASP.NET Core. ويستند SDK خدمة العامل أيضا على مبادئ مماثلة. قم بإجراء جميع تغييرات التكوين تقريبا في ConfigureServices() القسم عن طريق استدعاء الأساليب المناسبة على IServiceCollection، كما هو مفصل في القسم التالي.

إشعار

عند استخدام SDK هذا، لا يتم دعم تغيير التكوين عن طريق التعديل TelemetryConfiguration.Active ولن تنعكس التغييرات.

استخدام ApplicationInsightsServiceOptions

يمكنك تعديل بعض الإعدادات الشائعة عن طريق التمرير ApplicationInsightsServiceOptions إلى، كما في هذا AddApplicationInsightsTelemetryWorkerService المثال:

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

لاحظ أن ApplicationInsightsServiceOptions في SDK يكون في مساحة الاسم Microsoft.ApplicationInsights.WorkerService على عكس Microsoft.ApplicationInsights.AspNetCore.Extensions في ASP.NET Core SDK.

يسرد الجدول التالي الإعدادات شائعة الاستخدام في ApplicationInsightsServiceOptions.

الإعدادات	‏‏الوصف	الإعداد الافتراضي
تمكين QuickPulseMetricStream	تمكين/تعطيل ميزة القياسات المباشرة.	صواب
EnableAdaptiveSampling	تمكين/تعطيل أخذ العينات التكيفية.	صواب
EnableHeartbeat	تمكين/تعطيل ميزة Heartbeats، التي ترسل بشكل دوري (افتراضي 15 دقيقة) مقياسا مخصصا يسمى "HeartBeatState" مع معلومات حول وقت التشغيل مثل إصدار .NET وبيئة Azure، إذا كان ذلك ممكنا.	صواب
AddAutoCollectedMetricExtractor	تمكين/تعطيل مستخرج AutoCollectedMetrics، وهو معالج بيانات تتبع الاستخدام الذي يرسل مقاييس مجمعة مسبقا حول الطلبات/التبعيات قبل أخذ العينات.	صواب
EnableDiagnosticsTelemetryModule	تمكين/تعطيل`DiagnosticsTelemetryModule` سيؤدي تعطيل هذا الإعداد إلى تجاهل الإعدادات التالية: `EnableHeartbeat`و `EnableAzureInstanceMetadataTelemetryModule`و.`EnableAppServicesHeartbeatTelemetryModule`	صواب

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

أخذ عينات

يدعم Application Insights SDK لخدمة العامل كلا من أخذ العينات بمعدل ثابت وأخذ العينات التكيفية. يتم تمكين أخذ العينات التكيفية بشكل افتراضي. يمكن تعطيل أخذ العينات باستخدام EnableAdaptiveSampling الخيار في ApplicationInsightsServiceOptions.

لتكوين إعدادات أخذ العينات الأخرى، يمكنك استخدام المثال التالي:

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetry(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

لمزيد من المعلومات، راجع مستند أخذ العينات .

إضافة مهيئات بيانات تتبع الاستخدام

استخدم مُهيِّئات بيانات تتبع الاستخدام عندما ترغب في تعريف الخصائص التي يتم إرسالها مع كل بيانات تتبع الاستخدام.

أضف أي مهيئ بيانات تتبع الاستخدام جديد إلى الحاوية DependencyInjection وتضيفها SDK تلقائيا إلى TelemetryConfiguration.

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

إزالة مهيئات بيانات تتبع الاستخدام

توجد مُهيئات بيانات تتبع الاستخدام بشكل افتراضي. لإزالة جميع بيانات تتبع الاستخدام أو المُحددة منها، استخدم نموذج التعليمات البرمجية التالي بعد الاتصال AddApplicationInsightsTelemetryWorkerService().

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

إضافة معالجات بيانات تتبع الاستخدام

يمكنك إضافة معالجات بيانات تتبع الاستخدامTelemetryConfigurationباستخدام طريقة الامتدادAddApplicationInsightsTelemetryProcessor فيIServiceCollection. يمكنك استخدام معالجات بيانات تتبع الاستخدام في سيناريوهات التصفية المتقدمة للسماح بمزيد من التحكم المباشر في ما يتم تضمينه أو استبعاده من بيانات تتبع الاستخدام التي ترسلها إلى Application Insights. استخدم المثال التالي:

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();
        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
    }

تكوين وحدات القياس عن بعد الافتراضية أو إزالتها

يستخدم Application Insights وحدات بيانات تتبع الاستخدام لتجميع بيانات تتبع الاستخدام حول أحمال عمل معينة تلقائيًا دون الحاجة إلى تتبع يدوي بواسطة المستخدم.

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

DependencyTrackingTelemetryModule
PerformanceCollectorModule
QuickPulseTelemetryModule
AppServicesHeartbeatTelemetryModule (هناك حاليا مشكلة تتعلق بوحدة القياس عن بعد هذه. للحصول على حل بديل مؤقت، راجع GitHub Issue 1689.)
AzureInstanceMetadataTelemetryModule

لتكوين أي وحدة نمطية افتراضية لبيانات تتبع الاستخدام، استخدم أسلوب ConfigureTelemetryModule<T> الملحق على IServiceCollection، كما هو موضح في المثال التالي:

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "keyhere";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

تكوين قناة بيانات تتبع الاستخدام

القناة الافتراضية هي ServerTelemetryChannel. يمكنك تجاوزه كما يظهر المثال التالي:

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

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

إذا كنت تريد تعطيل بيانات تتبع الاستخدام بشكل مشروط وديناميكي، فيمكنك TelemetryConfigurationحل المثيل باستخدام حاوية حقن التبعية ASP.NET Core في أي مكان في التعليمات البرمجيةDisableTelemetry الخاصة بك وتعيين العلامة عليها.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

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

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

ما هي الحزمة التي يجب أن أستخدمها؟

سيناريو تطبيق .NET Core	الحزمة
بدون HostedServices	WorkerService
مع HostedServices	AspNetCore (not WorkerService)
مع HostedServices، مراقبة HostedServices فقط	WorkerService (سيناريو نادر)

هل يمكن لـ HostedServices داخل تطبيق .NET Core باستخدام حزمة AspNetCore إدخال TelemetryClient فيه؟

نعم. ستتم مشاركة التكوين مع بقية تطبيق الويب.

كيف يمكنني تتبع بيانات تتبع الاستخدام الذي لا يتم جمعه تلقائيًا؟

الحصول على مثيل TelemetryClient باستخدام حقن الدالة الإنشائية واستدعاء الأسلوب المطلوب TrackXXX() عليه. لا نوصي بإنشاء مثيلات TelemetryClient جديدة. تم تسجيل مثيل أحادي من TelemetryClient بالفعل في الحاوية DependencyInjection ، والتي تشترك TelemetryConfiguration مع بقية بيانات تتبع الاستخدام. يوصى بإنشاء مثيل جديدTelemetryClientفقط إذا كان يحتاج إلى تكوين منفصل عن باقي بيانات تتبع الاستخدام.

هل يمكنني استخدام Visual Studio IDE لتهيئة Application Insights لمشروع خدمة العامل؟

يتم حاليا دعم إلحاق Visual Studio IDE فقط لتطبيقات ASP.NET/ASP.NET Core. سيتم تحديث هذا المستند عندما يقوم Visual Studio بشحن الدعم لإلحاق تطبيقات Worker Service.

هل يمكنني تمكين مراقبة Application Insights باستخدام أدوات مثل Azure Monitor Application Insights Agent (سابقًا Status Monitor v2)؟

‏‏لا. يدعم عامل Azure Monitor Application Insights حاليا .NET فقط.

هل يتم دعم جميع الميزات إذا قمت بتشغيل تطبيقي في Linux؟

نعم. دعم ميزة SDK هو نفسه في جميع الأنظمة الأساسية، مع الاستثناءات التالية:

يتم دعم عدّادات الأداء في Windows فقط باستثناء عملية وحدة المعالجة المركزية/الذاكرة المُوضحة في المقاييس المباشرة.

وعلى الرغم من تمكين ServerTelemetryChannel افتراضيًا، إذا كان التطبيق يعمل في Linux أو macOS، فلن تقوم القناة تلقائيًا بإنشاء مجلد تخزين محلي للاحتفاظ ببيانات تتبع الاستخدام مؤقتًا إذا كانت هناك مشكلات في الشبكة. وبسبب هذا القيد، يتم فقدان القياس عن بعد عند وجود مشاكل مؤقتة في الشبكة أو الخادم. للتغلب على هذه المشكلة، تكوين مجلد محلي للقناة:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

    public void ConfigureServices(IServiceCollection services)
    {
        // The following will configure the channel to use the given folder to temporarily
        // store telemetry items during network or Application Insights server issues.
        // User should ensure that the given folder already exists
        // and that the application has read/write permissions.
        services.AddSingleton(typeof(ITelemetryChannel),
                                new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
        services.AddApplicationInsightsTelemetryWorkerService();
    }

التطبيقات النموذج

تطبيق وحدة تحكم .NET Core: استخدم هذا النموذج إذا كنت تستخدم تطبيق وحدة تحكم مكتوبا إما في .NET Core (2.0 أو أعلى) أو .NET Framework (4.7.2 أو أعلى).

ASP.NET مهام الخلفية الأساسية باستخدام HostedServices: استخدم هذه العينة إذا كنت في ASP.NET Core وقم بإنشاء مهام الخلفية وفقا للتوجيهات الرسمية.

.NET Core Worker Service: استخدم هذه العينة إذا كان لديك تطبيق .NET Worker Service وفقا للتوجيهات الرسمية.

عدة تطوير البرامج SDK مفتوحة المصدر

قراءة الرمز والمساهمة فيه.

للحصول على آخر التحديثات وإصلاحات الأخطاء، راجع ملاحظات الإصدار.

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

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

تطبيقات Application Insights لخدمة العامل (تطبيقات بخلاف تطبيقات HTTP)

السيناريوهات المدعومة

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

استخدام Application Insights SDK لخدمة العامل

تطبيق .NET Core Worker Service

مهام خلفية ASP.NET Core مع الخدمات المستضافة

تطبيق وحدة تحكم .NET Core/.NET Framework

تشغيل التطبيق الخاص بك

القياسات المباشرة

سجلات ILogger

التبعيات

EventCounter

تعقب بيانات تتبع الاستخدام الأخرى يدويا

قم بتكوين Application Insights SDK

استخدام ApplicationInsightsServiceOptions

أخذ عينات

إضافة مهيئات بيانات تتبع الاستخدام

إزالة مهيئات بيانات تتبع الاستخدام

إضافة معالجات بيانات تتبع الاستخدام

تكوين وحدات القياس عن بعد الافتراضية أو إزالتها

تكوين قناة بيانات تتبع الاستخدام

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

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

ما هي الحزمة التي يجب أن أستخدمها؟

هل يمكن لـ HostedServices داخل تطبيق .NET Core باستخدام حزمة AspNetCore إدخال TelemetryClient فيه؟

كيف يمكنني تتبع بيانات تتبع الاستخدام الذي لا يتم جمعه تلقائيًا؟

هل يمكنني استخدام Visual Studio IDE لتهيئة Application Insights لمشروع خدمة العامل؟

هل يمكنني تمكين مراقبة Application Insights باستخدام أدوات مثل Azure Monitor Application Insights Agent (سابقًا Status Monitor v2)؟

هل يتم دعم جميع الميزات إذا قمت بتشغيل تطبيقي في Linux؟

التطبيقات النموذج

عدة تطوير البرامج SDK مفتوحة المصدر

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

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