Logboekregistratie met de Azure SDK voor .NET

Artikel
04/09/2024

De Azure SDK voor . De clientbibliotheken van NET bevatten de mogelijkheid om clientbibliotheekbewerkingen te registreren. 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
Toewijzen aan ASP.NET Core-logboekregistratie

Belangrijk

Dit artikel is van toepassing op clientbibliotheken die gebruikmaken van de meest recente versies van de Azure SDK voor .NET. Als u wilt zien of een bibliotheek wordt ondersteund, raadpleegt u de lijst met nieuwste versies van Azure SDK. Als uw app een oudere versie van een Azure SDK-clientbibliotheek gebruikt, raadpleegt u specifieke instructies in de toepasselijke servicedocumentatie.

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
Uitgaande aanvraagheaders

HTTP-antwoordlogboekvermelding:

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

HTTP-aanvraag- en antwoordinhoud:

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

Notitie

Logboekregistratie van inhoud is standaard uitgeschakeld. Zie HTTP-aanvraag- en antwoordteksten voor logboeken om deze 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 reactie-gebeurtenissen
Waarschuwing voor fouten
Uitgebreid voor gedetailleerde berichten en logboekregistratie van inhoud

Logboekregistratie met ingebouwde methoden inschakelen

De Azure SDK voor . Clientbibliotheken van NET registreren 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();

Logboekregistratie bij diagnostische traceringen

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

In dit voorbeeld wordt het logboekniveau uitgebreid 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 wel kunt verwerken. Bovendien kunt u bij het maken van het exemplaar 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 op deze gebeurtenissen die worden verzonden vanuit de Azure Core-clientbibliotheek met een uitgebreid niveau. De Azure Core-bibliotheek maakt gebruik van de naam van een gebeurtenisbron.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);

Toewijzen aan ASP.NET Core-logboekregistratie

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.

Azure SDK `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Logboekregistratie met clientregistratie

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

Installeer het Microsoft.Extensions.Azure NuGet-pakket:
```
dotnet add package Microsoft.Extensions.Azure
```
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"));
    azureBuilder.UseCredential(new DefaultAzureCredential());
});
```
In het voorgaande voorbeeld wordt de methode gebruikt AddAzureClients :
- Registreert de volgende objecten met de container voor afhankelijkheidsinjectie (DI):
  - Service voor doorstuurserver voor logboeken
  - Azure Service Bus-client
- Hiermee stelt u de standaardtokenreferentie in die moet worden gebruikt voor alle geregistreerde clients.
Wijzig in appsettings.json het standaardlogboekniveau van de Service Bus-bibliotheek. U kunt Debug deze bijvoorbeeld als volgt instellen door de Logging:LogLevel:Azure.Messaging.ServiceBus sleutel 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 service bus-clientgebeurtenissen geregistreerd EventLevel.Verbose .

Logboekregistratie zonder clientregistratie

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:

Voer in deze scenario's de volgende stappen uit:

Installeer het Microsoft.Extensions.Azure NuGet-pakket:
```
dotnet add package Microsoft.Extensions.Azure
```

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

Haal de service voor logboekstuurserver op uit de DI-container en roep de Start bijbehorende 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();

Wijzig in appsettings.json het standaardlogboekniveau van de Azure Core-bibliotheek. U kunt Debug deze bijvoorbeeld als volgt instellen door de Logging:LogLevel:Azure.Core sleutel 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 geregistreerd EventLevel.Verbose .

Zie Logboekregistratie in .NET Core en ASP.NET Core voor 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:

Installeer het NuGet-pakket Azure.Monitor.OpenTelemetry.AspNetCore :
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Maak of registreer de client van de bibliotheek. De distributie ondersteunt beide gevallen.
```
await using var client = new ServiceBusClient("<connection_string>");
```
Wijzig in appsettings.json het standaardlogboekniveau van de Service Bus-bibliotheek. U kunt Debug deze bijvoorbeeld als volgt instellen door de Logging:LogLevel:Azure.Messaging.ServiceBus sleutel 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 service bus-clientgebeurtenissen geregistreerd EventLevel.Verbose .

HTTP-aanvraag- en antwoordteksten registreren

Notitie

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.

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:

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

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

Methode	Instructies
Logboekregistratie met ingebouwde methoden inschakelen	Doorgeven `EventLevel.Verbose` of doorgeven aan `AzureEventSourceListener.CreateConsoleLogger` of `EventLevel.LogAlwaysAzureEventSourceListener.CreateTraceLogger`
Aangepaste logboekregistratie configureren	De constructorparameter van de `AzureEventSourceListener` klasse `level` instellen op `EventLevel.Verbose` of `EventLevel.LogAlways`
Toewijzen 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

Delen via