Rejestrowanie Szczegółowe informacje aplikacji przy użyciu platformy .NET

Z tego artykułu dowiesz się, jak przechwytywać dzienniki przy użyciu aplikacji Szczegółowe informacje w aplikacjach platformy .NET przy użyciu pakietu dostawcyMicrosoft.Extensions.Logging.ApplicationInsights. Jeśli używasz tego dostawcy, możesz wykonywać zapytania i analizować dzienniki przy użyciu narzędzi usługi Application Insights.

Uwaga

Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Szczegółowe informacje. Długoterminowy plan Szczegółowe informacje aplikacji polega na zbieraniu danych przy użyciu biblioteki OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, Python i Java applications).

Uwaga

Jeśli chcesz zaimplementować pełny zakres danych telemetrycznych usługi Application Szczegółowe informacje wraz z rejestrowaniem, zobacz Konfigurowanie Szczegółowe informacje aplikacji dla witryn internetowych ASP.NET lub aplikacji Szczegółowe informacje dla aplikacji ASP.NET Core.

Napiwek

Microsoft.ApplicationInsights.WorkerService Pakiet NuGet używany do włączania Szczegółowe informacje aplikacji dla usług w tle jest poza zakresem. Aby uzyskać więcej informacji, zobacz Application Szczegółowe informacje for Worker Service apps (Aplikacja Szczegółowe informacje dla aplikacji usługi Worker Service).

aplikacje ASP.NET Core

Aby dodać rejestrowanie Szczegółowe informacje aplikacji do aplikacji ASP.NET Core:

1. Zainstaluj program Microsoft.Extensions.Logging.ApplicationInsights.

2. Dodaj ApplicationInsightsLoggerProviderpolecenie :

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

Po zainstalowaniu pakietu NuGet i zarejestrowaniu dostawcy za pomocą iniekcji zależności aplikacja jest gotowa do rejestrowania. W przypadku iniekcji ILogger konstruktora wymagana jest alternatywa ILogger<TCategoryName> typu ogólnego lub ogólnego. Po rozwiązaniu ApplicationInsightsLoggerProvider tych implementacji udostępnia je. Zarejestrowane komunikaty lub wyjątki są wysyłane do Szczegółowe informacje aplikacji.

Rozważmy następujący przykładowy kontroler:

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

Aby uzyskać więcej informacji, zobacz Rejestrowanie w ASP.NET Core i Jaki typ telemetrii aplikacji Szczegółowe informacje jest generowany z dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w aplikacji Szczegółowe informacje?.

Aplikacja konsolowa

Aby dodać rejestrowanie aplikacji Szczegółowe informacje do aplikacji konsolowych, najpierw zainstaluj następujące pakiety NuGet:

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

W poniższym przykładzie użyto pakietu Microsoft.Extensions.Logging.Application Szczegółowe informacje i pokazano domyślne zachowanie aplikacji konsolowej. Pakiet Microsoft.Extensions.Logging.Application Szczegółowe informacje powinien być używany w aplikacji konsolowej lub zawsze, gdy potrzebujesz minimalnej implementacji aplikacji Szczegółowe informacje bez pełnego zestawu funkcji, takiego jak metryki, śledzenie rozproszone, próbkowanie i inicjatory telemetrii.

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

Aby uzyskać więcej informacji, zobacz What Application Szczegółowe informacje telemetry type is produced from ILogger logs? (Jaki typ telemetrii aplikacji Szczegółowe informacje jest generowany na podstawie dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w aplikacji Szczegółowe informacje?.

Zakresy rejestrowania

ApplicationInsightsLoggingProvider obsługuje zakresy dzienników. Zakresy są domyślnie włączone.

Jeśli zakres jest typu IReadOnlyCollection<KeyValuePair<string,object>>, każda para klucz/wartość w kolekcji zostanie dodana do telemetrii Application Szczegółowe informacje jako właściwości niestandardowych. W poniższym przykładzie dzienniki są przechwytywane jako TraceTelemetry i mają ("MyKey", "MyValue") właściwości .

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

Jeśli jakikolwiek inny typ jest używany jako zakres, jest przechowywany w ramach właściwości Scope w usłudze Application Szczegółowe informacje telemetrii. W poniższym przykładzie TraceTelemetry ma właściwość o nazwie Scope , która zawiera zakres.

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

Często zadawane pytania

Jaki typ telemetrii Szczegółowe informacje aplikacji jest generowany z dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w aplikacji Szczegółowe informacje?

ApplicationInsightsLoggerProvider przechwytuje ILogger dzienniki i tworzy TraceTelemetry je na ich podstawie. Exception Jeśli obiekt zostanie przekazany do metody w metodzie w ILoggermetodzie Log , ExceptionTelemetry zostanie utworzony zamiast TraceTelemetry.

Wyświetlanie telemetrii ILogger

W witrynie Azure Portal:

1. Przejdź do witryny Azure Portal i uzyskaj dostęp do zasobu Szczegółowe informacje aplikacji.
2. Kliknij sekcję "Dzienniki" w Szczegółowe informacje aplikacji.
3. Użyj język zapytań Kusto (KQL), aby wykonywać zapytania dotyczące komunikatów ILogger, zwykle przechowywanych w traces tabeli.
   • Przykładowe zapytanie: traces | where message contains "YourSearchTerm".
4. Uściślij zapytania, aby filtrować dane ILogger według ważności, zakresu czasu lub określonej zawartości wiadomości.

W programie Visual Studio (debuger lokalny):

1. Uruchom aplikację w trybie debugowania w programie Visual Studio.
2. Otwórz okno "Narzędzia diagnostyczne", gdy aplikacja jest uruchomiona.
3. Na karcie "Zdarzenia" dzienniki ILogger są wyświetlane wraz z innymi danymi telemetrycznymi.
4. Skorzystaj z funkcji wyszukiwania i filtrowania w oknie "Narzędzia diagnostyczne", aby zlokalizować określone komunikaty ILogger.

Jeśli wolisz zawsze wysyłać TraceTelemetry, użyj tego fragmentu kodu:

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

Dlaczego niektóre dzienniki ILogger nie mają tych samych właściwości co inne?

Aplikacja Szczegółowe informacje przechwytuje i wysyła ILogger dzienniki przy użyciu tych samych TelemetryConfiguration informacji, które są używane dla każdej innego telemetrii. Ale jest wyjątek. Domyślnie TelemetryConfiguration nie jest w pełni konfigurowany podczas logowania z Program.cs lub Startup.cs. Dzienniki z tych miejsc nie mają konfiguracji domyślnej, więc nie są uruchomione wszystkie TelemetryInitializer wystąpienia i TelemetryProcessor wystąpienia.

Używam autonomicznego pakietu Microsoft.Extensions.Logging.Application Szczegółowe informacje i chcę ręcznie rejestrować więcej niestandardowych danych telemetrycznych. Jak to zrobić?

W przypadku korzystania z pakietu TelemetryClient autonomicznego nie jest wstrzykiwany do kontenera wstrzykiwania zależności (DI). Musisz utworzyć nowe wystąpienie i TelemetryClient użyć tej samej konfiguracji, której używa dostawca rejestratora, jak pokazano w poniższym kodzie. To wymaganie gwarantuje, że ta sama konfiguracja jest używana dla wszystkich niestandardowych danych telemetrycznych i telemetrii z programu 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;
   }  
}

Uwaga

Jeśli używasz pakietu do włączenia Microsoft.ApplicationInsights.AspNetCore Szczegółowe informacje aplikacji, zmodyfikuj ten kod, aby uzyskać TelemetryClient bezpośrednio w konstruktorze.

Nie mam zainstalowanego zestawu SDK i używam rozszerzenia Azure Web Apps, aby włączyć aplikację Szczegółowe informacje dla aplikacji ASP.NET Core. Jak mogę użyć nowego dostawcy?

Rozszerzenie application Szczegółowe informacje w usłudze Azure Web Apps używa nowego dostawcy. Reguły filtrowania można zmodyfikować w pliku appsettings.json dla aplikacji.

Następne kroki

• Rejestrowanie na platformie .NET
• Rejestrowanie w usłudze ASP.NET Core
• Dzienniki śledzenia platformy .NET w Szczegółowe informacje aplikacji