.NET için Azure SDK ile günlüğe kaydetme

Makale
04/09/2024

için Azure SDK'sı. NET'in istemci kitaplıkları, istemci kitaplığı işlemlerini günlüğe kaydetme özelliğini içerir. Bu günlük, istemci kitaplıklarının Azure hizmetlerine yaptığı G/Ç isteklerini ve yanıtlarını izlemenizi sağlar. Günlükler genellikle iletişim sorunlarının hatalarını ayıklamak veya tanılamak için kullanılır. Bu makalede, .NET için Azure SDK ile günlüğe kaydetmeyi etkinleştirmek için aşağıdaki yaklaşımlar açıklanmaktadır:

Yerleşik yöntemlerle günlüğe kaydetmeyi etkinleştirme
Özel günlüğü yapılandırma
ASP.NET Core günlüğüne eşleme

Önemli

Bu makale, .NET için Azure SDK'nın en son sürümlerini kullanan istemci kitaplıkları için geçerlidir. Bir kitaplığın desteklenip desteklenmediğini görmek için Azure SDK'nın en son sürümleri listesine bakın. Uygulamanız Azure SDK istemci kitaplığının eski bir sürümünü kullanıyorsa, ilgili hizmet belgelerindeki belirli yönergelere bakın.

Günlük bilgileri

SDK, kişisel verileri kaldırmak için parametre sorgusu ve üst bilgi değerlerini temizleyerek her HTTP isteğini ve yanıtını günlüğe kaydeder.

HTTP istek günlüğü girişi:

Benzersiz Kimlik
HTTP yöntemi
URI
Giden istek üst bilgileri

HTTP yanıt günlüğü girdisi:

G/Ç işleminin süresi (geçen süre)
Request ID
HTTP durum kodu
HTTP neden tümceciği
Yanıt üst bilgileri
Uygun olduğunda hata bilgileri

HTTP isteği ve yanıt içeriği:

üst bilgiye bağlı Content-Type olarak metin veya bayt olarak içerik akışı.

Not

İçerik günlüğü varsayılan olarak devre dışıdır. Etkinleştirmek için bkz . HTTP isteğini ve yanıt gövdelerini günlüğe kaydetme. Bu özellik yalnızca BIR Azure hizmetiyle iletişim kurmak için HTTP kullanan kitaplıklar için geçerlidir. AMQP gibi alternatif protokollere dayalı kitaplıklar içerik günlüğünü desteklemez. Desteklenmeyen örnekler arasında Event Hubs, Service Bus ve Web PubSub gibi Azure hizmetlerine yönelik kitaplıklar yer alır.

Olay günlükleri genellikle şu üç düzeyden birinde çıkış olur:

İstek ve yanıt olayları için bilgilendirme
Hatalar için uyarı
Ayrıntılı iletiler ve içerik günlüğü için ayrıntılı bilgi

Yerleşik yöntemlerle günlüğe kaydetmeyi etkinleştirme

için Azure SDK'sı. NET'in istemci kitaplıkları olayları .NET için tipik olan sınıfı aracılığıyla System.Diagnostics.Tracing.EventSource Windows için Olay İzleme'ye (ETW) kaydeder. Olay kaynakları, uygulamanızda en düşük performans yüküyle yapılandırılmış günlükleri kullanmanıza olanak sağlar. Olay günlüklerine erişmek için olay dinleyicilerini kaydetmeniz gerekir.

SDK, .NET uygulamanız için kapsamlı günlüğe kaydetmeyi Azure.Core.Diagnostics.AzureEventSourceListener basitleştiren iki statik yöntem içeren sınıfını içerir: CreateConsoleLogger ve CreateTraceLogger. Bu yöntemlerin her biri, günlük düzeyini belirten isteğe bağlı bir parametre kabul eder. Parametresi sağlanmadıysa varsayılan günlük düzeyi Informational kullanılır.

Konsol penceresinde oturum açın

.NET istemci kitaplıkları için Azure SDK'nın temel ağlarından biri, kapsamlı günlükleri gerçek zamanlı olarak görüntüleme özelliğini basitleştirmektir. yöntemi, CreateConsoleLogger günlükleri konsol penceresine tek bir kod satırıyla göndermenizi sağlar:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Tanılama izlemelerine günlüğe kaydetme

İzleme dinleyicileri uygularsanız, yöntemini kullanarak CreateTraceLogger standart .NET olay izleme mekanizmasına (System.Diagnostics.Tracing ) oturum açabilirsiniz. .NET'te olay izleme hakkında daha fazla bilgi için bkz . İzleme Dinleyicileri.

Bu örnek, ayrıntılı günlük düzeyini belirtir:

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

Özel günlüğü yapılandırma

Yukarıda belirtildiği gibi, .NET için Azure SDK'dan günlük iletileri almak için olay dinleyicilerini kaydetmeniz gerekir. Yukarıdaki basitleştirilmiş yöntemlerden birini kullanarak kapsamlı günlük kaydı uygulamak istemiyorsanız sınıfının bir örneğini AzureEventSourceListener oluşturabilirsiniz. Bu örneği yazdığınız bir geri çağırma yöntemi geçirin. Bu yöntem, işlemeniz gereken günlük iletilerini alır. Ayrıca, örneği oluştururken, eklenecek günlük düzeylerini belirtebilirsiniz.

Aşağıdaki örnek, konsolda özel bir iletiyle oturum açan bir olay dinleyicisi oluşturur. Günlükler, Azure Core istemci kitaplığından yayılan olaylara göre bir ayrıntı düzeyiyle filtrelenir. Azure Core kitaplığı olay kaynağı adını Azure-Corekullanır.

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

ASP.NET Core günlüğüne eşleme

Hizmet, AzureEventSourceLogForwarder günlük kaydı için standart ASP.NET Core günlük yapılandırmasını kullanmanızı sağlar. Hizmet, Azure SDK olay kaynaklarından günlük iletilerini adresine ILoggerFactoryiletir.

Aşağıdaki tabloda .NET EventLevel için Azure SDK'sının ASP.NET Core LogLevelile nasıl eşildiği açıklanmaktadır.

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

İstemci kaydıyla günlüğe kaydetme

Örnek olarak Azure Service Bus kitaplığını kullanarak aşağıdaki adımları tamamlayın:

Microsoft.Extensions.Azure NuGet paketini yükleyin:
```
dotnet add package Microsoft.Extensions.Azure
```
Program.cs'da, uzantı yöntemine bir çağrı yoluyla Azure SDK kitaplığının istemcisini AddAzureClients kaydedin:
```
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());
});
```
Yukarıdaki örnekte AddAzureClients yöntemi:
- Bağımlılık ekleme (DI) kapsayıcısıyla aşağıdaki nesneleri kaydeder:
  - Günlük ileticisi hizmeti
  - Azure Service Bus istemcisi
- Tüm kayıtlı istemciler için kullanılacak varsayılan belirteç kimlik bilgilerini ayarlar.
appsettings.json service bus kitaplığının varsayılan günlük düzeyini değiştirin. Örneğin, Debug anahtarı aşağıdaki gibi ayarlayarak Logging:LogLevel:Azure.Messaging.ServiceBus geçiş yapın:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Anahtar olarak ayarlandığından Logging:LogLevel:Azure.Messaging.ServiceBusDebug, en fazla Service Bus istemci olayları günlüğe EventLevel.Verbose kaydedilir.

İstemci kaydı olmadan günlüğe kaydetme

Bir Azure SDK kitaplığının istemcisini DI kapsayıcısıyla kaydetmenin imkansız veya gereksiz olduğu senaryolar vardır:

Azure SDK kitaplığı, DI kapsayıcısına istemci IServiceCollection kaydetmek için bir uzantı yöntemi içermez.
Uygulamanız, diğer Azure SDK kitaplıklarına bağlı Olan Azure uzantı kitaplıklarını kullanır. Bu tür Azure uzantı kitaplıklarına örnek olarak şunlar verilebilir:

Bu senaryolarda aşağıdaki adımları tamamlayın:

Microsoft.Extensions.Azure NuGet paketini yükleyin:
```
dotnet add package Microsoft.Extensions.Azure
```

Program.cs günlük ileticisi hizmetini DI kapsayıcısında tekil olarak kaydedin:

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

DI kapsayıcısından günlük ileticisi hizmetini getirin ve yöntemini çağırın Start . Örneğin, ASP.NET Core Razor Pages sayfa modeli sınıfında oluşturucu ekleme kullanarak:

using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Azure;

public class IndexModel : PageModel
{
    public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
        logForwarder.Start();

appsettings.json'de Azure Core kitaplığının varsayılan günlük düzeyini değiştirin. Örneğin, Debug anahtarı aşağıdaki gibi ayarlayarak Logging:LogLevel:Azure.Core geçiş yapın:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Anahtar olarak ayarlandığından Logging:LogLevel:Azure.CoreDebug, en fazla Azure Core kitaplık olayları günlüğe EventLevel.Verbose kaydedilir.

Daha fazla bilgi için, bkz. .NET Core ve ASP.NET Core'da günlüğe kaydetme.

Azure.Monitor.OpenTelemetry.AspNetCore kullanarak günlüğe kaydetme

Sürümünden 1.2.0başlayarak Azure İzleyici OpenTelemetry dağıtımı, Azure istemci kitaplıklarından gelen günlüklerin yakalanmasını destekler. .NET Core ve ASP.NET Core'da günlüğe kaydetme bölümünde açıklanan yapılandırma seçeneklerinden herhangi birini kullanarak günlüğü denetleyebilirsiniz.

Örnek olarak Azure Service Bus kitaplığını kullanarak aşağıdaki adımları tamamlayın:

Azure.Monitor.OpenTelemetry.AspNetCore NuGet paketini yükleyin:
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Kitaplığın istemcisini oluşturun veya kaydedin. Dağıtım her iki durumda da destek sunar.
```
await using var client = new ServiceBusClient("<connection_string>");
```
appsettings.json service bus kitaplığının varsayılan günlük düzeyini değiştirin. Örneğin, Debug anahtarı aşağıdaki gibi ayarlayarak Logging:LogLevel:Azure.Messaging.ServiceBus geçiş yapın:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Anahtar olarak ayarlandığından Logging:LogLevel:Azure.Messaging.ServiceBusDebug, en fazla Service Bus istemci olayları günlüğe EventLevel.Verbose kaydedilir.

HTTP isteğini ve yanıt gövdelerini günlüğe kaydetme

Not

Bu özellik yalnızca BIR Azure hizmetiyle iletişim kurmak için HTTP kullanan kitaplıklar için geçerlidir. AMQP gibi alternatif protokollere dayalı kitaplıklar içerik günlüğünü desteklemez. Desteklenmeyen örnekler arasında Event Hubs, Service Bus ve Web PubSub gibi Azure hizmetlerine yönelik kitaplıklar yer alır.

İstemci kitaplığında beklenmeyen davranış sorunlarını giderirken, aşağıdaki öğeleri incelemek yararlı olur:

Temel alınan Azure hizmetinin REST API'sine gönderilen HTTP isteği gövdesi.
Azure hizmetinin REST API'sinden alınan HTTP yanıt gövdesi.

Varsayılan olarak, yukarıda belirtilen içeriğin günlüğe kaydedilmesi devre dışı bırakılır. HTTP isteğinin ve yanıt gövdelerinin günlüğe kaydedilmesini etkinleştirmek için aşağıdaki adımları tamamlayın:

İstemci seçenekleri nesnesinin IsLoggingContentEnabled özelliğini olarak trueayarlayın ve options nesnesini istemcinin oluşturucusna geçirin. Örneğin, Azure Key Vault Gizli Dizileri kitaplığına yönelik HTTP isteklerini ve yanıtlarını günlüğe kaydetmek için:
```
var clientOptions = new SecretClientOptions
{
    Diagnostics = 
    {
        IsLoggingContentEnabled = true,
    }
};
var client = new SecretClient(
    new Uri("https://<keyvaultname>.vault.azure.net/"),
    new DefaultAzureCredential(),
    clientOptions);
```

Ayrıntılı/hata ayıklama veya daha yüksek bir olay/günlük düzeyiyle tercih ettiğiniz günlük yaklaşımını kullanın. Belirli yönergeler için aşağıdaki tabloda yaklaşımınızı bulun.

Yaklaşım	Yönergeler
Yerleşik yöntemlerle günlüğe kaydetmeyi etkinleştirme	Veya veya'ya `EventLevel.LogAlways` geçirme `EventLevel.VerboseAzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger`
Özel günlüğü yapılandırma	Sınıfın `AzureEventSourceListenerlevel` oluşturucu parametresini veya olarak `EventLevel.Verbose` ayarlayın `EventLevel.LogAlways`
ASP.NET Core günlüğüne eşleme	appsettings.json ekle `"Azure.Core": "Debug"`

Sonraki adımlar

Azure App Service’te uygulamalar için tanılama günlüğünü etkinleştirme
Azure güvenlik günlüğü ve denetim seçeneklerini gözden geçirme
Azure platform günlükleriyle çalışmayı öğrenin
.NET günlüğü ve izlemesi hakkında daha fazla bilgi edinin