Application Insights-Protokollierung mit .NET

In diesem Artikel erfahren Sie, wie Sie Protokolle mit Application Insights in .NET-Apps mithilfe des Microsoft.Extensions.Logging.ApplicationInsights-Anbieterpakets erfassen. Wenn Sie diesen Anbieter verwenden, können Sie Ihre Protokolle mithilfe der Application Insights-Tools abfragen und analysieren.

Hinweis

Die folgende Dokumentation basiert auf der klassischen Application Insights-API. Der langfristige Plan für Application Insights besteht darin, Daten mithilfe von OpenTelemetry zu sammeln. Weitere Informationen finden Sie unter Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python- und Java-Anwendungen.

Hinweis

Wenn Sie den gesamten Umfang der Application Insights-Telemetriedaten zusammen mit der Protokollierung implementieren möchten, lesen Sie Konfigurieren von Application Insights für Ihre ASP.NET-Website oder Application Insights für ASP.NET Core-Anwendungen.

Tipp

Das NuGet-Paket Microsoft.ApplicationInsights.WorkerService, das zum Aktivieren von Application Insights für Hintergrunddienste verwendet wird, liegt außerhalb des Bereichs. Weitere Informationen finden Sie unter Application Insights für Workerdienst-Apps.

ASP.NET Core-Anwendungen

So fügen Sie Application Insights-Protokollierung zu ASP.NET Core-Anwendungen hinzu:

1. Installieren Sie Microsoft.Extensions.Logging.ApplicationInsights.

2. Fügen Sie ApplicationInsightsLoggerProvider hinzu:

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

Wenn das NuGet-Paket installiert ist und der Anbieter mit Abhängigkeitsinjektion registriert wird, kann die App Protokollierungen vornehmen. Bei Konstruktorinjektion ist entweder ILogger oder die generische Alternative ILogger<TCategoryName> erforderlich. Wenn diese Implementierungen aufgelöst werden, stellt ApplicationInsightsLoggerProvider diese zur Verfügung. Protokollierte Meldungen oder Ausnahmen werden zu Application Insights gesendet.

Betrachten Sie den folgenden Beispielcontroller:

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

Weitere Informationen finden Sie unter Protokollierung in ASP.NET Core und Welcher Application Insights-Telemetrietyp wird aus ILogger-Protokollen erstellt? Wo kann ich ILogger-Protokolle in Application Insights sehen?.

Konsolenanwendung

Um die Application Insights-Protokollierung zu Konsolenanwendungen hinzuzufügen, installieren Sie zuerst die folgenden NuGet-Pakete:

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

Im folgenden Beispiel wird das Paket Microsoft.Extensions.Logging.ApplicationInsights verwendet und das Standardverhalten für eine Konsolenanwendung veranschaulicht. Das Paket Microsoft.Extensions.Logging.ApplicationInsights sollte in einer Konsolenanwendung oder immer dann verwendet werden, wenn Sie eine Minimalimplementierung von Application Insights ohne den vollständigen Featuresatz wie Metriken, verteilte Ablaufverfolgung, Sampling und Telemetrieinitialisierer wünschen.

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

Weitere Informationen finden Sie unter Welcher Application Insights-Telemetrietyp wird aus ILogger-Protokollen erstellt? Wo kann ich ILogger-Protokolle in Application Insights sehen?.

Protokollierungsbereiche

ApplicationInsightsLoggingProvider unterstützt Protokollbereiche. Bereiche sind standardmäßig aktiviert.

Bei einem Bereich vom Typ IReadOnlyCollection<KeyValuePair<string,object>> wird jedes Schlüssel-Wert-Paar in der Sammlung als benutzerdefinierte Eigenschaft zur Application Insights-Telemetrie hinzugefügt. Im folgenden Beispiel werden Protokolle als TraceTelemetry aufgezeichnet und enthalten ("MyKey", "MyValue") in den Eigenschaften.

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

Wenn ein anderer Typ als Bereich verwendet wird, wird er unter der Eigenschaft Scope in der Application Insights-Telemetrie gespeichert. Im folgenden Beispiel verfügt TraceTelemetry über eine Eigenschaft namens Scope, die den Bereich enthält.

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

Häufig gestellte Fragen

Welcher Typ von Application Insights-Telemetriedaten wird anhand von ILogger-Protokollen erstellt? Wo kann ich ILogger-Protokolle in Application Insights einsehen?

ApplicationInsightsLoggerProvider erfasst ILogger-Protokolle und erstellt TraceTelemetry daraus. Wenn ein Exception-Objekt an die Log-Methode in ILogger übergeben wird, wird anstelle von TraceTelemetryExceptionTelemetry erstellt.

Anzeigen der ILogger-Telemetrie

Im Azure-Portal:

1. Wechseln Sie zum Azure-Portal, und greifen Sie auf Ihre Application Insights-Ressource zu.
2. Klicken Sie in Application Insights auf den Abschnitt „Protokolle“.
3. Verwenden Sie Kusto Query Language (KQL), um ILogger-Nachrichten abzufragen. Diese sind normalerweise in der Tabelle traces gespeichert.
   • Beispielabfrage: traces | where message contains "YourSearchTerm".
4. Verfeinern Sie Ihre Abfragen, um ILogger-Daten nach Schweregrad, Zeitbereich oder bestimmten Nachrichteninhalten zu filtern.

Gehen Sie in Visual Studio (lokaler Debugger) folgendermaßen vor:

1. Starten Sie Ihre Anwendung in Visual Studio im Debugmodus.
2. Öffnen Sie das Fenster „Diagnosetools“, während die Anwendung ausgeführt wird.
3. Auf der Registerkarte „Ereignisse“ werden ILogger-Protokolle zusammen mit anderen Telemetriedaten angezeigt.
4. Verwenden Sie die Such- und Filterfunktionen im Fenster „Diagnosetools“, um bestimmte ILogger-Nachrichten zu suchen.

Wenn Sie immer TraceTelemetry senden möchten, verwenden Sie diesen Codeausschnitt:

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

Warum weisen einige ILogger-Protokolle nicht dieselben Eigenschaften wie andere auf?

Application Insights erfasst und sendet ILogger-Protokolle mithilfe derselben TelemetryConfiguration-Informationen, die auch für andere Telemetriedaten verwendet werden. Es gibt jedoch eine Ausnahme. Standardmäßig ist die TelemetryConfiguration nicht vollständig eingerichtet, wenn Sie aus Program.cs oder Startup.cs protokollieren. Protokolle aus diesen Quellen weisen nicht die Standardkonfiguration auf, daher führen sie nicht alle TelemetryInitializer- und TelemetryProcessor-Instanzen aus.

Ich verwende das eigenständige Paket „Microsoft.Extensions.Logging.ApplicationInsights“ und möchte weitere benutzerdefinierte Telemetriedaten manuell protokollieren. Wie sollte ich dazu vorgehen?

Wenn Sie das eigenständige Paket verwenden, wird TelemetryClient nicht in den Abhängigkeitseinschleusungscontainer (Dependency Injection, DI) eingeschleust. Sie müssen eine neue Instanz von TelemetryClient erstellen und dieselbe Konfiguration verwenden, die der Protokollierungsanbieter verwendet, wie im folgenden Code gezeigt. Durch diese Anforderung wird sichergestellt, dass dieselbe Konfiguration für alle benutzerdefinierten Telemetriedaten sowie für die Telemetriedaten von ILogger verwendet wird.

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

Hinweis

Wenn Sie Application Insights mit dem Paket Microsoft.ApplicationInsights.AspNetCore aktivieren, ändern Sie diesen Code, um TelemetryClient direkt in den Konstruktor abzurufen.

Ich habe das SDK nicht installiert und verwende die Azure-Web-Apps-Erweiterung, um Application Insights für meine ASP.NET Core-Anwendungen zu aktivieren. Wie verwende ich den neuen Anbieter?

Die Application Insights-Erweiterung in Azure-Web-Apps verwendet den neuen Anbieter. Sie können die Filterregeln in der Datei appsettings.json für die Anwendung ändern.

Nächste Schritte

• Protokollierung in .NET
• Protokollierung in ASP.NET Core
• .NET-Ablaufverfolgungsprotokolle in Application Insights