Freigeben über

Application Insights-Protokollierung mit .NET

  • Artikel

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 und unserer OpenTelemetry Roadmap. Migrationsleitfaden sind für .NET, Node.js und Python verfügbar.

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:

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();

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:

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.

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

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 Umfang 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, die in der Tabelle traces gespeichert sind. 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 und andere Telemetriedaten angezeigt.
  4. Verwenden Sie die Such- und Filterfeatures 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