تسجيل الدخول إلى Application Insights باستخدام NET.

في هذه المقالة، ستتعلم كيفية تسجيل السجلات باستخدام Application Insights في تطبيقات .NET باستخدام حزمة Microsoft.Extensions.Logging.ApplicationInsights الموفر. إذا كنت تستخدم هذا الموفر، يمكنك الاستعلام عن سجلاتك وتحليلها باستخدام أدوات Application Insights.

إشعار

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

إشعار

إذا كنت ترغب في تنفيذ النطاق الكامل من بيانات تتبع الاستخدام ل Application Insights جنبا إلى جنب مع التسجيل، فشاهد تكوين Application Insights لمواقع الويب ASP.NET أو Application Insights لتطبيقات ASP.NET Core.

تلميح

تعد حزمة Microsoft.ApplicationInsights.WorkerService NuGet، المستخدمة لتمكين Application Insights لخدمات الخلفية، خارج النطاق. لمزيد من المعلومات، راجع Application Insights لـWorker Service.

تطبيقات ASP.NET Core

لإضافة تسجيل Application Insights إلى تطبيقات ASP.NET Core:

1. Microsoft.Extensions.Logging.ApplicationInsightsقم بتثبيت .

2. إضافة ApplicationInsightsLoggerProvider:

.NET 6.0+

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

.NET 5.0

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;

namespace WebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = CreateHostBuilder(args).Build();

            var logger = host.Services.GetRequiredService<ILogger<Program>>();
            logger.LogInformation("From Program, running the host now.");

            host.Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                })
                .ConfigureLogging((context, builder) =>
                {
                    builder.AddApplicationInsights(
                        configureTelemetryConfiguration: (config) => config.ConnectionString = context.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"],
                        configureApplicationInsightsLoggerOptions: (options) => { }
                    );

                    // Capture all log-level entries from Startup
                    builder.AddFilter<ApplicationInsightsLoggerProvider>(
                        typeof(Startup).FullName, LogLevel.Trace);
                });
    }
}

مع تثبيت حزمة NuGet، وتسجيل الموفر مع حقن التبعية، يكون التطبيق جاهزاً لتسجيل الدخول. مع حقن الدالة الإنشائية إما ILogger أو مطلوب بديل من النوع ILogger<TCategoryName> العام. عند حل هذه التطبيقات، ApplicationInsightsLoggerProvider يوفرها. يتم إرسال الرسائل أو الاستثناءات المسجلة إلى Application Insights.

خذ بعين الاعتبار وحدة تحكم المثال التالي:

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

لمزيد من المعلومات، راجع تسجيل الدخول ASP.NET Core وما نوع بيانات تتبع الاستخدام Application Insights الذي يتم إنتاجه من سجلات ILogger؟ أين يمكنني رؤية سجلات ILogger في Application Insights؟.

تطبيق وحدة التحكم

لإضافة تسجيل Application Insights إلى تطبيقات وحدة التحكم، قم أولا بتثبيت حزم NuGet التالية:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

يستخدم المثال التالي حزمة Microsoft.Extensions.Logging.ApplicationInsights ويوضح السلوك الافتراضي لتطبيق وحدة التحكم. يجب استخدام حزمة Microsoft.Extensions.Logging.ApplicationInsights في تطبيق وحدة تحكم أو كلما كنت تريد الحد الأدنى من تنفيذ Application Insights دون مجموعة الميزات الكاملة مثل المقاييس والتتبع الموزع وأخذ العينات ومهايئات القياس عن بعد.

.NET 6.0+

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

.NET 5.0

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System;
using System.Threading.Tasks;

namespace ConsoleApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            using var channel = new InMemoryChannel();

            try
            {
                IServiceCollection services = new ServiceCollection();
                services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
                services.AddLogging(builder =>
                {
                    // Only Application Insights is registered as a logger provider
                    builder.AddApplicationInsights(
                        configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
                        configureApplicationInsightsLoggerOptions: (options) => { }
                    );
                });

                IServiceProvider serviceProvider = services.BuildServiceProvider();
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                logger.LogInformation("Logger is working...");
            }
            finally
            {
                // Explicitly call Flush() followed by Delay, as required in console apps.
                // This ensures that even if the application terminates, telemetry is sent to the back end.
                channel.Flush();

                await Task.Delay(TimeSpan.FromMilliseconds(1000));
            }
        }
    }
}

لمزيد من المعلومات، راجع ما نوع بيانات تتبع الاستخدام Application Insights الذي يتم إنتاجه من سجلات ILogger؟ أين يمكنني رؤية سجلات ILogger في Application Insights؟.

نطاقات التسجيل

ApplicationInsightsLoggingProvider يدعم نطاقات السجل. يتم تمكين النطاقات بشكل افتراضي.

إذا كان النطاق من النوع IReadOnlyCollection<KeyValuePair<string,object>>، ثم تتم إضافة كل زوج مفتاح/قيمة في المجموعة إلى بيانات تتبع الاستخدام لـApplication Insights كخصائص مخصصة. في المثال التالي، يتم التقاط السجلات كما TraceTelemetry ولها ("MyKey", "MyValue") في الخصائص.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

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

    using (_logger.BeginScope("hello scope"))
    {
        _logger.LogError("An example of an Error level message");
    }

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

ما هو بيانات تتبع الاستخدام لـApplication Insights يتم إنتاجها من سجلات ILogger؟ أين يمكنني رؤية سجلات ILogger في Application Insights؟

ApplicationInsightsLoggerProvider يلتقط سجلات ILogger ويخلق TraceTelemetry منها. إذا تم تمرير كائن Exception إلى الطريقة Log،في ILogger و ExceptionTelemetry يتم إنشاؤه بدلاً من TraceTelemetry.

عرض بيانات تتبع استخدام ILogger

في مدخل Microsoft Azure:

1. انتقل إلى مدخل Microsoft Azure والوصول إلى مورد Application Insights الخاص بك.
2. انقر على قسم "Logs" داخل Application Insights.
3. استخدم Kusto Query Language (KQL) للاستعلام عن رسائل ILogger، المخزنة عادة في traces الجدول.
   • مثال استعلام: traces | where message contains "YourSearchTerm".
4. تحسين الاستعلامات لتصفية بيانات ILogger حسب الخطورة أو النطاق الزمني أو محتوى رسالة محدد.

في Visual Studio (مصحح الأخطاء المحلي):

1. ابدأ تشغيل التطبيق الخاص بك في وضع التصحيح داخل Visual Studio.
2. افتح نافذة "أدوات التشخيص" أثناء تشغيل التطبيق.
3. في علامة التبويب "الأحداث"، تظهر سجلات ILogger مع بيانات تتبع الاستخدام الأخرى.
4. استخدم ميزات البحث والتصفية في نافذة "أدوات التشخيص" لتحديد موقع رسائل ILogger معينة.

إذا كنت تفضل إرسال TraceTelemetry دائماً، استخدم هذا القصاصة البرمجية:

builder.AddApplicationInsights(
    options => options.TrackExceptionsAsExceptionTelemetry = false);

لماذا بعض سجلات ILogger ليس لها نفس خصائص الآخرين؟

Application Insights يلتقط ويرسل سجلات ILogger باستخدام نفس TelemetryConfiguration المعلومات المستخدمة في كل القياس عن بعد الأخرى. لكن هناك استثناء. بشكل افتراضي، لا يتم إعداد TelemetryConfiguration بالكامل عند التسجيل من Program.cs أو Startup.cs. لا تحتوي السجلات من هذه الأماكن على التكوين الافتراضي، لذلك لا تقوم بتشغيل جميع TelemetryInitializer المثيلات والمثيلات TelemetryProcessor .

أنا أستخدم الحزمة المستقلة Microsoft.Extensions.Logging.ApplicationInsights، وأريد تسجيل المزيد من القياس عن بُعد المخصص يدوياً. كيف أفعل ذلك؟

عند استخدام الحزمة المستقلة، لا يتم إدخال TelemetryClient في حاوية إدخال التبعية (DI). تحتاج إلى إنشاء مثيل جديد من TelemetryClient واستخدام نفس التكوين الذي يستخدمه موفر المسجل كما يظهر التعليمات البرمجية التالية. يضمن هذا المطلب استخدام نفس التكوين لجميع عمليات القياس عن بُعد والقياس عن بُعد المخصصة من ILogger.

public class MyController : ApiController
{
   // This TelemetryClient instance can be used to track additional telemetry through the TrackXXX() API.
   private readonly TelemetryClient _telemetryClient;
   private readonly ILogger _logger;

   public MyController(IOptions<TelemetryConfiguration> options, ILogger<MyController> logger)
   {
        _telemetryClient = new TelemetryClient(options.Value);
        _logger = logger;
   }  
}

إشعار

إذا كنت تستخدم الحزمة Microsoft.ApplicationInsights.AspNetCore لتمكين Application Insights تعديل هذه التعليمات البرمجية للحصول TelemetryClient مباشرة في المنشئ.

ليس لديّ SDK مثبتة، وأنا أستخدم ملحق Azure Web Apps لتمكين Application Insights لتطبيقاتي الأساسية ASP.NET. كيف يمكنني استخدام الموفر الجديد؟

يستخدم ملحق Application Insights في Azure Web Apps الموفر الجديد. يمكنك تعديل قواعد التصفية في appsettings.js في الملف للتطبيق الخاص بك.

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

• تسجيل الدخول .NET
• تسجيل الدخول ASP.NET الأساسية
• تسجيل الدخول في Application Insights