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 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:
Installieren Sie
Microsoft.Extensions.Logging.ApplicationInsights
.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 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 TraceTelemetry
ExceptionTelemetry
erstellt.
Anzeigen der ILogger-Telemetrie
Im Azure-Portal:
- Wechseln Sie zum Azure-Portal, und greifen Sie auf Ihre Application Insights-Ressource zu.
- Klicken Sie in Application Insights auf den Abschnitt „Protokolle“.
- Verwenden Sie Kusto Query Language (KQL), um ILogger-Nachrichten abzufragen. Diese sind normalerweise in der Tabelle
traces
gespeichert.- Beispielabfrage:
traces | where message contains "YourSearchTerm"
.
- Beispielabfrage:
- 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:
- Starten Sie Ihre Anwendung in Visual Studio im Debugmodus.
- Öffnen Sie das Fenster „Diagnosetools“, während die Anwendung ausgeführt wird.
- Auf der Registerkarte „Ereignisse“ werden ILogger-Protokolle zusammen mit anderen Telemetriedaten angezeigt.
- 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
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter:Einreichen und Feedback anzeigen für