Pencatatan Application Insights dengan.NET

Dalam artikel ini, Anda mempelajari cara mengambil log dengan Application Insights di aplikasi .NET dengan menggunakan Microsoft.Extensions.Logging.ApplicationInsights paket penyedia. Jika menggunakan penyedia ini, Anda dapat membuat kueri dan menganalisis log menggunakan alat Application Insights.

Catatan

Dokumentasi berikut bergantung pada API klasik Application Insights. Rencana jangka panjang untuk Application Insights adalah mengumpulkan data menggunakan OpenTelemetry. Untuk informasi selengkapnya, lihat Mengaktifkan Azure Monitor OpenTelemetry untuk aplikasi .NET, Node.js, Python, dan Java.

Catatan

Jika Anda ingin menerapkan berbagai telemetri Application Insights bersama dengan pengelogan, lihat Mengonfigurasi Application Insights untuk situs web ASP.NET atau Application Insights untuk aplikasi ASP.NET Core.

Tip

Paket Microsoft.ApplicationInsights.WorkerService NuGet, yang digunakan untuk mengaktifkan Application Insights untuk layanan latar belakang, berada di luar cakupan. Untuk informasi selengkapnya, lihat Application Insights untuk aplikasi Layanan Pekerja.

Aplikasi ASP.NET Core

Untuk menambahkan pengelogan Application Insights ke aplikasi ASP.NET Core:

1. Instal Microsoft.Extensions.Logging.ApplicationInsights.

2. Tambahkan 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);
                });
    }
}

Dengan paket NuGet terpasang, dan penyedia sedang terdaftar dengan injeksi dependensi, aplikasi siap untuk mencatat. Dengan injeksi konstruktor, diperlukan ILogger atau alternatif jenis generik ILogger<TCategoryName>. Ketika implementasi ini diselesaikan, ApplicationInsightsLoggerProvider berikan. Pesan atau pengecualian yang dicatat dikirim ke Application Insights.

Perhatikan contoh pengontrol berikut:

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" };
    }
}

Untuk informasi selengkapnya, lihat Pengelogan di ASP.NET Core dan Jenis telemetri Application Insights apa yang dihasilkan dari log ILogger? Di mana saya dapat melihat log ILogger di Application Insights?.

Aplikasi konsol

Untuk menambahkan pengelogan Application Insights ke aplikasi konsol, pertama-tama instal paket NuGet berikut:

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

Contoh berikut menggunakan paket Microsoft.Extensions.Logging.ApplicationInsights dan menunjukkan perilaku default untuk aplikasi konsol. Paket Microsoft.Extensions.Logging.ApplicationInsights harus digunakan dalam aplikasi konsol atau setiap kali Anda menginginkan implementasi minimum Application Insights tanpa set fitur lengkap seperti metrik, pelacakan terdistribusi, pengambilan sampel, dan penginisialisasi telemetri.

.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));
            }
        }
    }
}

Untuk informasi selengkapnya, lihat Jenis telemetri Application Insights apa yang dihasilkan dari log ILogger? Di mana saya dapat melihat log ILogger di Application Insights?.

Cakupan pencatatan

ApplicationInsightsLoggingProvider mendukung cakupan log. Cakupan diaktifkan secara default.

Jika cakupan berdasarkan jenis IReadOnlyCollection<KeyValuePair<string,object>>, setiap pasangan nilai kunci dalam koleksi ditambahkan ke telemetri Application Insights sebagai properti kustom. Dalam contoh berikut, log diambil sebagai TraceTelemetry dan memiliki ("MyKey", "MyValue") di properti.

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

Jika ada jenis lain yang digunakan sebagai cakupan, jenis tersebut disimpan di bawah properti Scope dalam telemetri Application Insights. Dalam contoh berikut, TraceTelemetry memiliki properti yang disebut Scope yang berisi cakupan.

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

Pertanyaan yang Sering Ditanyakan

Jenis telemetri Application Insights apa yang dihasilkan dari catatan ILogger? Di mana saya dapat melihat log ILogger di Application Insights?

ApplicationInsightsLoggerProvider mengambil ILogger log dan membuat TraceTelemetry darinya. Jika objek Exception dilweatkan ke metode Log pada ILogger, ExceptionTelemetry dibuat dan bukan TraceTelemetry.

Melihat Telemetri ILogger

Di Portal Microsoft Azure:

1. Buka Portal Microsoft Azure dan akses sumber daya Application Insights Anda.
2. Klik bagian "Log" di dalam Application Insights.
3. Gunakan Bahasa Kueri Kusto (KQL) untuk mengkueri pesan ILogger, biasanya disimpan dalam traces tabel.
   • Contoh Kueri: traces | where message contains "YourSearchTerm".
4. Perbaiki kueri Anda untuk memfilter data ILogger berdasarkan tingkat keparahan, rentang waktu, atau konten pesan tertentu.

Di Visual Studio (Debugger Lokal):

1. Mulai aplikasi Anda dalam mode debug dalam Visual Studio.
2. Buka jendela "Alat Diagnostik" saat aplikasi berjalan.
3. Di tab "Peristiwa", log ILogger muncul bersama dengan data telemetri lainnya.
4. Gunakan fitur pencarian dan filter di jendela "Alat Diagnostik" untuk menemukan pesan ILogger tertentu.

Jika Anda lebih suka selalu mengirimTraceTelemetry, gunakan cuplikan ini:

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

Mengapa beberapa catatan ILogger tidak memiliki properti yang sama dengan yang lain?

Application Insights mengambil dan mengirim log ILogger dengan menggunakan informasi TelemetryConfiguration yang sama yang digunakan untuk telemetri lainnya. Tapi ada pengecualian. Secara default, TelemetryConfiguration tidak sepenuhnya diatur saat Anda mencatat dari Program.cs atau Startup.cs. Log dari tempat-tempat ini tidak memiliki konfigurasi default, sehingga tidak menjalankan semua TelemetryInitializer instans dan TelemetryProcessor instans.

Saya menggunakan paket mandiri Microsoft.Extensions.Logging.ApplicationInsights, dan saya ingin mencatat beberapa telemetri kustom tambahan secara manual. Bagaimana aku harus melakukan itu?

Ketika Anda menggunakan paket mandiri, TelemetryClient tidak disuntikkan ke kontainer injeksi dependensi (DI). Anda perlu membuat instans baru TelemetryClient dan menggunakan konfigurasi yang sama dengan yang digunakan penyedia logger, seperti yang ditunjukkan oleh kode berikut. Ini memastikan bahwa konfigurasi yang sama digunakan untuk semua telemetri kustom serta telemetri dari 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;
   }  
}

Catatan

Jika Anda menggunakan Microsoft.ApplicationInsights.AspNetCore paket untuk mengaktifkan Application Insights, ubah kode ini untuk mendapatkan TelemetryClient langsung masuk ke konstruktor.

Saya tidak memiliki SDK yang terpasang, dan saya menggunakan ekstensi Azure Web Apps untuk mengaktifkan Application Insights untuk aplikasi ASP.NET Core saya. Bagaimana cara Saya menggunakan penyedia baru?

Ekstensi Application Insights di Azure Web Apps menggunakan penyedia baru. Anda dapat mengubah aturan pemfilteran di appsettings.json file untuk aplikasi Anda.

Langkah berikutnya

• Pengelogan dalam .NET
• Pengelogan di ASP.NET Core
• .NET melacak catatan dalam Application Insights