Ereignisse
Nehmen Sie sich die Microsoft Learn-Herausforderung an
19. Nov., 23 Uhr - 10. Jan., 23 Uhr
Ignite Edition - Erstellen Sie Fähigkeiten in Microsoft Azure und verdienen Sie bis zum 10. Januar ein digitales Badge!
Jetzt registrierenDieser Browser wird nicht mehr unterstützt.
Führen Sie ein Upgrade auf Microsoft Edge durch, um die neuesten Features, Sicherheitsupdates und den technischen Support zu nutzen.
Die Clientbibliotheken des Azure SDK für .NET umfassen die Möglichkeit, Vorgänge von Clientbibliotheken zu protokollieren. Diese Protokollierung ermöglicht es Ihnen, E/A-Anforderungen und -Antworten zu überwachen, die Clientbibliotheken an Azure-Dienste senden. In der Regel werden die Protokolle verwendet, um Kommunikationsprobleme zu debuggen oder zu diagnostizieren. In diesem Artikel werden die folgenden Ansätze beschrieben, mit denen sich die Protokollierung mit dem Azure SDK für .NET konfigurieren lässt:
Wichtig
Dieser Artikel bezieht sich auf die Clientbibliotheken, die die neuesten Versionen des Azure SDK für .NET verwenden. Informationen dazu, ob eine Bibliothek unterstützt wird, finden Sie in der Liste mit den neuesten Azure SDK-Releases. Wenn Ihre App eine ältere Version einer Azure SDK-Clientbibliothek verwendet, finden Sie spezifische Anweisungen in der entsprechenden Dienstdokumentation.
Das SDK protokolliert jede HTTP-Anforderung und -Antwort und bereinigt die Abfrage- und Headerwerte der Parameter, um personenbezogene Daten zu entfernen.
Protokolleintrag der HTTP-Anforderung:
Protokolleintrag der HTTP-Antwort:
HTTP-Anforderung- und -Antwortinhalt:
Ob im Inhaltsdatenstrom Text oder Byte übertragen werden, ist abhängig vom Content-Type
-Header.
Hinweis
Die Inhaltsprotokollierung ist standardmäßig deaktiviert. Informationen zum Aktivieren finden Sie unter Protokollieren von HTTP-Anforderungs- und -Antworttexten. Diese Funktion gilt nur für Bibliotheken, die HTTP für die Kommunikation mit einem Azure-Dienst verwenden. Bibliotheken, die auf alternativen Protokollen wie AMQP basieren, unterstützen die Inhaltsprotokollierung nicht. Nicht unterstützte Beispiele umfassen Bibliotheken für Azure-Dienste wie Event Hubs, Service Bus und Web PubSub.
Ereignisprotokolle werden in der Regel auf einer der folgenden drei Ebenen ausgegeben:
Die Clientbibliotheken des Azure SDK für .NET protokollieren Ereignisse in der Ereignisablaufverfolgung für Windows (ETW) über die System.Diagnostics.Tracing.EventSource-Klasse, was typisch für .NET ist. Mit Ereignisquellen können Sie die strukturierte Protokollierung in Ihrer App mit minimalem Leistungsmehraufwand verwenden. Sie müssen nur die Ereignislistener registrieren, um Zugriff auf diese Ereignisprotokolle zu erhalten.
Das SDK enthält die Klasse Azure.Core.Diagnostics.AzureEventSourceListener, die zwei statische Methoden enthält, die die umfassende Protokollierung für Ihre .NET-App vereinfachen: CreateConsoleLogger
und CreateTraceLogger
. Jede dieser Methoden akzeptiert einen optionalen Parameter, der einen Protokolliergrad angibt. Wenn der Parameter nicht angegeben wird, wird der Standardprotokolliergrad von Informational
verwendet.
Eine der Hauptfunktionen des Azure SDK für .NET-Clientbibliotheken besteht darin, die Anzeige von umfassenden Protokollen in Echtzeit zu vereinfachen. Mit der Methode CreateConsoleLogger
können Sie Protokolle mit einer einzelnen Codezeile an das Konsolenfenster senden:
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateConsoleLogger();
Wenn Sie Ablaufverfolgungslistener implementieren, können Sie mit der Methode CreateTraceLogger
in der standardmäßigen .NET-Ereignisablaufverfolgung (System.Diagnostics.Tracing) protokollieren. Weitere Informationen zur Ereignisablaufverfolgung in .NET finden Sie unter Ablaufverfolgungslistener.
In diesem Beispiel wird die Protokollebene „Ausführlich“ dargestellt:
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);
Wie bereits erwähnt, müssen Sie Ereignislistener registrieren, um vom Azure SDK für .NET Protokollmeldungen zu empfangen. Wenn Sie die umfassende Protokollierung nicht mithilfe der oben genannten vereinfachten Methoden implementieren möchten, können Sie eine Instanz der AzureEventSourceListener
-Klasse erstellen. Übergeben Sie eine Rückrufmethode, die Sie schreiben, an diese Instanz. Diese Methode empfängt Protokollmeldungen, die Sie nach Bedarf verarbeiten lassen können. Wenn Sie die Instanz erstellen, können Sie außerdem die zu berücksichtigenden Protokollebenen angeben.
Im folgenden Beispiel wird ein Ereignislistener erstellt, der mit einer benutzerdefinierten Meldung in die Konsole protokolliert. Die Protokolle werden nach diesen Ereignissen gefiltert, die von der Azure Core-Clientbibliothek mit dem Grad „Ausführlich“ ausgegeben werden. Die Azure Core-Bibliothek verwendet den Ereignisquellennamen Azure-Core
.
using Azure.Core.Diagnostics;
using System.Diagnostics.Tracing;
// code omitted for brevity
using var listener = new AzureEventSourceListener((e, message) =>
{
// Only log messages from "Azure-Core" event source
if (e.EventSource.Name == "Azure-Core")
{
Console.WriteLine($"{DateTime.Now} {message}");
}
},
level: EventLevel.Verbose);
Mit dem Dienst AzureEventSourceLogForwarder können Sie die ASP.NET Core-Standardprotokollierungskonfiguration für die Protokollierung verwenden. Der Dienst leitet Protokollmeldungen von Azure SDK-Ereignisquellen an ILoggerFactory weiter.
Die folgende Tabelle zeigt, wie EventLevel
(Azure SDK für .NET) LogLevel
(ASP.NET Core) zugeordnet wird.
Azure SDK EventLevel |
ASP.NET Core LogLevel |
---|---|
Critical |
Critical |
Error |
Error |
Informational |
Information |
Warning |
Warning |
Verbose |
Debug |
LogAlways |
Information |
Führen Sie mit der Azure Service Bus-Bibliothek als Beispiel die folgenden Schritte aus:
Installieren Sie das NuGet-Paket Microsoft.Extensions.Azure:
dotnet add package Microsoft.Extensions.Azure
Registrieren Sie in der Datei Program.cs den Client der Azure SDK-Bibliothek über einen Aufruf der AddAzureClients-Erweiterungsmethode:
using Azure.Identity;
using Microsoft.Extensions.Azure;
// code omitted for brevity
builder.Services.AddAzureClients(azureBuilder =>
{
azureBuilder.AddServiceBusClient(
builder.Configuration.GetConnectionString("ServiceBus"));
azureBuilder.UseCredential(new DefaultAzureCredential());
});
Im vorangehenden Beispiel erledigt die AddAzureClients
-Methode Folgendes:
Ändern Sie in appsettings.json den Standardprotokolliergrad der Service Bus-Bibliothek. Ändern Sie sie beispielsweise in Debug
, indem Sie den Logging:LogLevel:Azure.Messaging.ServiceBus
-Schlüssel wie folgt festlegen:
{
"ConnectionStrings": {
"ServiceBus": "<connection_string>"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Azure.Messaging.ServiceBus": "Debug"
}
},
"AllowedHosts": "*"
}
Da der Schlüssel Logging:LogLevel:Azure.Messaging.ServiceBus
auf Debug
festgelegt ist, werden Service Bus-Clientereignisse bis EventLevel.Verbose
protokolliert.
Es gibt Szenarien, in denen die Registrierung des Clients einer Azure SDK-Bibliothek beim Container für die Abhängigkeitsinjektion entweder unmöglich oder unnötig ist:
IServiceCollection
-Erweiterungsmethode zum Registrieren eines Clients im Container für die Abhängigkeitsinjektion.Führen Sie in diesen Szenarien die folgenden Schritte aus:
Installieren Sie das NuGet-Paket Microsoft.Extensions.Azure:
dotnet add package Microsoft.Extensions.Azure
Registrieren Sie in Program.cs den Protokollweiterleitungsdienst als Singleton im Container für die Abhängigkeitsinjektion:
using Azure.Identity;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.Extensions.Azure;
using Microsoft.Extensions.DependencyInjection.Extensions;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>();
builder.Services.AddDataProtection()
.PersistKeysToAzureBlobStorage("<connection_string>", "<container_name>", "keys.xml")
.ProtectKeysWithAzureKeyVault(new Uri("<uri>"), new DefaultAzureCredential());
Rufen Sie den Protokollweiterleitungsdienst aus dem Container für die Abhängigkeitsinjektion ab, und rufen Sie seine Start-Methode auf. Beispiel: Verwenden der Konstruktorinjektion in einer ASP.NET Core Razor Pages-Seitenmodellklasse:
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Azure;
public class IndexModel : PageModel
{
public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
logForwarder.Start();
Ändern Sie in appsettings.json den Standardprotokolliergrad der Azure Core-Bibliothek. Ändern Sie sie beispielsweise in Debug
, indem Sie den Logging:LogLevel:Azure.Core
-Schlüssel wie folgt festlegen:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Azure.Core": "Debug"
}
},
"AllowedHosts": "*"
}
Da der Logging:LogLevel:Azure.Core
-Schlüssel auf Debug
festgelegt ist, werden Azure Core-Bibliotheksereignisse bis zum Grad EventLevel.Verbose
protokolliert.
Weitere Informationen finden Sie unter Protokollieren in .NET Core und ASP.NET Core.
Die Azure Monitor OpenTelemetry-Distribution, beginnend mit Version 1.2.0
, unterstützt das Erfassen von Protokollen aus Azure-Clientbibliotheken. Sie können die Protokollierung mithilfe einer der Konfigurationsoptionen steuern, die in Protokollierung in .NET Core und ASP.NET Core erläutert werden.
Führen Sie mit der Azure Service Bus-Bibliothek als Beispiel die folgenden Schritte aus:
Installieren Sie das NuGet Paket Azure.Monitor.OpenTelemetry.AspNetCore:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Erstellen oder registrieren Sie den Client der Bibliothek. Die Distribution unterstützt beide Fälle.
await using var client = new ServiceBusClient("<connection_string>");
Ändern Sie in appsettings.json den Standardprotokolliergrad der Service Bus-Bibliothek. Ändern Sie sie beispielsweise in Debug
, indem Sie den Logging:LogLevel:Azure.Messaging.ServiceBus
-Schlüssel wie folgt festlegen:
{
"ConnectionStrings": {
"ServiceBus": "<connection_string>"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Azure.Messaging.ServiceBus": "Debug"
}
},
"AllowedHosts": "*"
}
Da der Schlüssel Logging:LogLevel:Azure.Messaging.ServiceBus
auf Debug
festgelegt ist, werden Service Bus-Clientereignisse bis EventLevel.Verbose
protokolliert.
Hinweis
Diese Funktion gilt nur für Bibliotheken, die HTTP für die Kommunikation mit einem Azure-Dienst verwenden. Bibliotheken, die auf alternativen Protokollen wie AMQP basieren, unterstützen die Inhaltsprotokollierung nicht. Nicht unterstützte Beispiele umfassen Bibliotheken für Azure-Dienste wie Event Hubs, Service Bus und Web PubSub.
Bei der Problembehandlung von unerwartetem Verhalten einer Clientbibliothek ist es hilfreich, die folgenden Elemente zu untersuchen:
Die Protokollierung der oben genannten Inhalte ist standardmäßig deaktiviert. Um die Protokollierung der HTTP-Anforderungs- und -Antworttexte zu aktivieren, führen Sie die folgenden Schritte aus:
Legen Sie die IsLoggingContentEnabled-Eigenschaft des Objekts für Clientoptionen auf true
fest, und übergeben Sie das Objekt für Optionen an den Konstruktor des Clients. Um beispielsweise HTTP-Anforderungen und -Antworten für die Bibliothek der Azure Key Vault-Geheimnisse zu protokollieren:
var clientOptions = new SecretClientOptions
{
Diagnostics =
{
IsLoggingContentEnabled = true,
}
};
var client = new SecretClient(
new Uri("https://<keyvaultname>.vault.azure.net/"),
new DefaultAzureCredential(),
clientOptions);
Verwenden Sie Ihren bevorzugten Protokollierungsansatz mit einem Ereignis-/Protokolliergrad von „ausführlich/debuggen“ oder höher. Spezifische Anweisungen finden Sie in der folgenden Tabelle unter Ihrem Ansatz.
Vorgehensweise | Instructions |
---|---|
Aktivieren der Protokollierung mit integrierten Methoden | Übergeben von EventLevel.Verbose oder EventLevel.LogAlways an AzureEventSourceListener.CreateConsoleLogger oder AzureEventSourceListener.CreateTraceLogger |
Konfigurieren der benutzerdefinierten Protokollierung | Festlegen des Konstruktorparameters level der AzureEventSourceListener -Klasse auf EventLevel.Verbose oder EventLevel.LogAlways |
Zuordnen zur ASP.NET Core-Protokollierung | Hinzufügen von "Azure.Core": "Debug" zu appsettings.json |
Feedback zu .NET
.NET ist ein Open Source-Projekt. Wählen Sie einen Link aus, um Feedback zu geben:
Ereignisse
Nehmen Sie sich die Microsoft Learn-Herausforderung an
19. Nov., 23 Uhr - 10. Jan., 23 Uhr
Ignite Edition - Erstellen Sie Fähigkeiten in Microsoft Azure und verdienen Sie bis zum 10. Januar ein digitales Badge!
Jetzt registrierenTraining
Modul
Erfassen von Webanwendungsprotokollen mit der Diagnoseprotokollierung für App Service - Training
Erfahren Sie, wie Sie die Ausgabe der Ablaufverfolgung Ihrer Azure-Web-Apps erfassen. Zeigen Sie einen Liveprotokollstream an, und laden Sie Protokolldateien herunter, um sie offline zu analysieren.