Logging met de Azure SDK voor .NET

De clientbibliotheken van de Azure SDK voor .NET bevatten de mogelijkheid om clientbibliotheekbewerkingen te loggen. Met deze logboekregistratie kunt u I/O-aanvragen en -antwoorden bewaken die clientbibliotheken naar Azure-services maken. Normaal gesproken worden de logboeken gebruikt om communicatieproblemen op te sporen of te diagnosticeren. In dit artikel worden de volgende benaderingen beschreven voor het inschakelen van logboekregistratie met de Azure SDK voor .NET:

• Logboekregistratie met ingebouwde methoden inschakelen
• Aangepaste logboekregistratie configureren
• Koppelen aan ASP.NET Core-logboekregistratie

Logboekgegevens

De SDK registreert elke HTTP-aanvraag en -respons, waarbij de parameterquery en headerwaarden worden opgeschoond om persoonlijke gegevens te verwijderen.

Vermelding van HTTP-aanvraaglogboek:

• Unieke id
• HTTP-methode
• URI (Uniform Resource Identifier)
• Uitgaande aanvraagheaders

HTTP-antwoordlogboekvermelding:

• Duur van I/O-bewerking (verstreken tijd)
• Aanvraag-id
• HTTP-statuscode
• HTTP-redenzin
• Antwoordkopteksten
• Foutinformatie, indien van toepassing

HTTP-aanvraag- en antwoordinhoud:

• Inhoudsstroom als tekst of bytes, afhankelijk van de Content-Type koptekst.

  Opmerking

  Logboekregistratie van inhoud is standaard uitgeschakeld. Zie HTTP-verzoek- en antwoordlichamen loggen om het in te schakelen. Deze mogelijkheid is alleen van toepassing op bibliotheken die HTTP gebruiken om te communiceren met een Azure-service. Bibliotheken op basis van alternatieve protocollen, zoals AMQP, bieden geen ondersteuning voor logboekregistratie van inhoud. Niet-ondersteunde voorbeelden zijn bibliotheken voor Azure-services, zoals Event Hubs, Service Bus en Web PubSub.

Gebeurtenislogboeken worden meestal uitgevoerd op een van deze drie niveaus:

• Informatie over aanvraag- en reactiegebeurtenissen
• Waarschuwing voor fouten
• Uitgebreid voor gedetailleerde berichten en logboekregistratie van inhoud

Logboekregistratie met ingebouwde methoden inschakelen

De Azure SDK voor .NET-clientbibliotheken logt gebeurtenissen naar Event Tracing voor Windows (ETW) via de System.Diagnostics.Tracing.EventSource-klasse, wat gebruikelijk is voor .NET. Met gebeurtenisbronnen kunt u gestructureerde logboekregistratie in uw app gebruiken met minimale overhead voor prestaties. Als u toegang wilt krijgen tot de gebeurtenislogboeken, moet u gebeurtenislisteners registreren.

De SDK bevat de Azure.Core.Diagnostics.AzureEventSourceListener klasse, die twee statische methoden bevat waarmee uitgebreide logboekregistratie voor uw .NET-app wordt vereenvoudigd: CreateConsoleLogger en CreateTraceLogger. Elk van deze methoden accepteert een optionele parameter die een logboekniveau aangeeft. Als de parameter niet is opgegeven, wordt het standaardlogboekniveau Informational gebruikt.

Aanmelden bij het consolevenster

Een kerntenet van de Azure SDK voor .NET-clientbibliotheken is het vereenvoudigen van de mogelijkheid om uitgebreide logboeken in realtime weer te geven. Met de CreateConsoleLogger methode kunt u logboeken naar het consolevenster verzenden met één regel code:

using AzureEventSourceListener listener =
    AzureEventSourceListener.CreateConsoleLogger();

Loggen naar diagnostische traceringen

Als u traceringslisteners implementeert, kunt u de CreateTraceLogger methode gebruiken om te loggen naar het standaard .NET-mechanisme voor gebeurtenistracering (System.Diagnostics.Tracing). Zie Trace-listeners voor meer informatie over gebeurtenistracering in .NET.

In dit voorbeeld wordt een gedetailleerd logniveau opgegeven:

using AzureEventSourceListener listener =
    AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);

Aangepaste logboekregistratie configureren

Zoals hierboven vermeld, moet u gebeurtenislisteners registreren om logboekberichten te ontvangen van de Azure SDK voor .NET. Als u geen uitgebreide logboekregistratie wilt implementeren met behulp van een van de bovenstaande vereenvoudigde methoden, kunt u een exemplaar van de AzureEventSourceListener klasse maken. Geef die instantie een callback-methode door die u schrijft. Deze methode ontvangt logboekberichten die u op de manier die u nodig acht kunt verwerken. Bovendien kunt u bij het maken van de instantie de logboekniveaus opgeven die moeten worden opgenomen.

In het volgende voorbeeld wordt een gebeurtenislistener gemaakt die zich aanmeldt bij de console met een aangepast bericht. De logboeken worden gefilterd om alleen die gebeurtenissen te bevatten die worden gegenereerd vanuit de Azure Core-clientbibliotheek, met een gedetailleerd niveau. De Azure Core-bibliotheek maakt gebruik van de gebeurtenisbronnaam 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Koppelen met ASP.NET Core-logging

Met AzureEventSourceLogForwarder de service kunt u de standaardconfiguratie ASP.NET Core-logboekregistratie gebruiken voor logboekregistratie. De service stuurt logboekberichten van Azure SDK-gebeurtenisbronnen door naar ILoggerFactory.

In de volgende tabel ziet u hoe de Azure SDK voor .NET EventLevel wordt toegewezen aan de ASP.NET Core LogLevel.

Loggen met cliëntregistratie

Voer de volgende stappen uit met behulp van de Azure Service Bus-bibliotheek als voorbeeld:

1. Installeer het Microsoft.Extensions.Azure NuGet-pakket:

   dotnet add package Microsoft.Extensions.Azure
   

2. Registreer in Program.cs de client van de Azure SDK-bibliotheek via een aanroep naar de AddAzureClients extensiemethode:

   using Azure.Identity;
   using Microsoft.Extensions.Azure;
   
   // code omitted for brevity
   
   builder.Services.AddAzureClients(azureBuilder =>
   {
       azureBuilder.AddServiceBusClient(
           builder.Configuration.GetConnectionString("ServiceBus"));
   });
   

   In het voorgaande voorbeeld: de methode AddAzureClients.

   • Registreert de volgende objecten met de container voor afhankelijkheidsinjectie (DI):
     • Service voor doorstuurserver voor logboeken
     • Azure Service Bus-client
   • Wordt automatisch toegepast DefaultAzureCredential op verificatie, tenzij andere aanmeldgegevens expliciet zijn geconfigureerd.

3. Wijzig in appsettings.jsonhet standaardlogboekniveau van de Service Bus-bibliotheek. U kunt het bijvoorbeeld naar Debug schakelen door de Logging:LogLevel:Azure.Messaging.ServiceBus toets als volgt in te stellen:

   {
       "ConnectionStrings": {
           "ServiceBus": "<connection_string>"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning",
               "Azure.Messaging.ServiceBus": "Debug"
           }
       },
       "AllowedHosts": "*"
   }
   

   Omdat de Logging:LogLevel:Azure.Messaging.ServiceBus sleutel is ingesteld op Debug, zullen Service Bus-clientgebeurtenissen tot EventLevel.Verbose worden geregistreerd.

Loggen zonder klantregistratie

Er zijn scenario's waarin het registreren van de client van een Azure SDK-bibliotheek bij de DI-container onmogelijk of onnodig is:

• De Azure SDK-bibliotheek bevat IServiceCollection geen extensiemethode voor het registreren van een client in de DI-container.
• Uw app maakt gebruik van Azure-extensiebibliotheken die afhankelijk zijn van andere Azure SDK-bibliotheken. Voorbeelden van dergelijke Azure-extensiebibliotheken zijn:
  • Azure Key Vault-sleutelversleuteler voor DataProtection
  • Configuratieprovider voor geheimen van Azure Key Vault
  • Azure Blob Storage-sleutelarchief voor gegevensbescherming

Voer in deze scenario's de volgende stappen uit:

1. Installeer het Microsoft.Extensions.Azure NuGet-pakket:

   dotnet add package Microsoft.Extensions.Azure
   

2. Registreer in Program.cs de service voor het doorsturen van logboeken als een singleton in de DI-container:

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

3. Haal de logboekdoorstuurservice op uit de DI-container en roep de Start-methode aan. Gebruik bijvoorbeeld constructorinjectie in een ASP.NET Core Razor Pages-paginamodelklasse:

   using Microsoft.AspNetCore.Mvc.RazorPages;
   using Microsoft.Extensions.Azure;
   
   public class IndexModel : PageModel
   {
       public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
           logForwarder.Start();
   

4. Wijzig in appsettings.jsonhet standaardlogboekniveau van de Azure Core-bibliotheek. Zet het bijvoorbeeld op Debug door de sleutel Logging:LogLevel:Azure.Core als volgt in te stellen:

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning",
         "Azure.Core": "Debug"
       }
     },
     "AllowedHosts": "*"
   }
   

   Omdat de Logging:LogLevel:Azure.Core sleutel is ingesteld op Debug, worden Azure Core-bibliotheekgebeurtenissen EventLevel.Verbose geregistreerd.

Zie Logboekregistratie in .NET Core en ASP.NET Corevoor meer informatie.

Logboekregistratie met behulp van Azure.Monitor.OpenTelemetry.AspNetCore

De Distributie van Azure Monitor OpenTelemetry, vanaf versie 1.2.0, ondersteunt het vastleggen van logboeken die afkomstig zijn van Azure-clientbibliotheken. U kunt logboekregistratie beheren met behulp van een van de configuratieopties die worden besproken in Logboekregistratie in .NET Core en ASP.NET Core.

Voer de volgende stappen uit met behulp van de Azure Service Bus-bibliotheek als voorbeeld:

1. Installeer het NuGet-pakket Azure.Monitor.OpenTelemetry.AspNetCore :

   dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
   

2. Maak of registreer de client van de bibliotheek. De distributie ondersteunt beide gevallen.

   await using var client = new ServiceBusClient("<connection_string>");
   

3. Wijzig in appsettings.jsonhet standaardlogboekniveau van de Service Bus-bibliotheek. Stel het bijvoorbeeld in op Debug door de Logging:LogLevel:Azure.Messaging.ServiceBus toets als volgt in te stellen:

   {
       "ConnectionStrings": {
           "ServiceBus": "<connection_string>"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning",
               "Azure.Messaging.ServiceBus": "Debug"
           }
       },
       "AllowedHosts": "*"
   }
   

   Omdat de Logging:LogLevel:Azure.Messaging.ServiceBus sleutel is ingesteld op Debug, worden servicebus-clientgebeurtenissen tot EventLevel.Verbose gelogd.

HTTP-aanvraag- en antwoordteksten registreren

Bij het oplossen van problemen met onverwacht gedrag met een clientbibliotheek is het handig om de volgende items te controleren:

• De HTTP-aanvraagbody die is verzonden naar de REST API van de onderliggende Azure-service.
• De HTTP-antwoordtekst die is ontvangen van de REST API van de Azure-service.

Logboekregistratie van bovengenoemde inhoud is standaard uitgeschakeld. Voer de volgende stappen uit om logboekregistratie van de HTTP-aanvraag- en antwoordteksten in te schakelen:

1. Stel de eigenschap van IsLoggingContentEnabled het object clientopties in op trueen geef het optiesobject door aan de constructor van de client. Als u bijvoorbeeld HTTP-aanvragen en -antwoorden wilt registreren voor de Azure Key Vault Secrets-bibliotheek:

   var clientOptions = new SecretClientOptions
   {
       Diagnostics =
       {
           IsLoggingContentEnabled = true
       }
   };
   var client = new SecretClient(
       new Uri("https://<keyvaultname>.vault.azure.net/"),
       new DefaultAzureCredential(),
       clientOptions);
   

2. Gebruik uw voorkeur voor logboekregistratie met een gebeurtenis-/logboekniveau van gedetailleerd/foutopsporing of hoger. Zoek uw aanpak in de volgende tabel voor specifieke instructies.

   Methode	Aanwijzingen
   Logboekregistratie met ingebouwde methoden inschakelen	Geef EventLevel.Verbose of EventLevel.LogAlways door aan AzureEventSourceListener.CreateConsoleLogger of AzureEventSourceListener.CreateTraceLogger
   Aangepaste logboekregistratie configureren	De constructorparameter van de AzureEventSourceListener klasse level instellen op EventLevel.Verbose of EventLevel.LogAlways
   Koppelen aan ASP.NET Core-logboekregistratie	Toevoegen "Azure.Core": "Debug" aan appsettings.json

Volgende stappen

• diagnostische logboekregistratie inschakelen voor apps in Azure App Service
• Opties voor logboekregistratie en controle van Azure-beveiliging controleren
• Meer informatie over het werken met Azure-platformlogboeken
• Meer informatie over .NET-logboekregistratie en tracering