Pengelogan dengan Azure SDK untuk .NET

Artikel
04/09/2024

Azure SDK untuk pustaka klien .NET mencakup kemampuan untuk mencatat operasi pustaka klien. Pengelogan ini memungkinkan Anda memantau permintaan dan respons I/O yang dilakukan pustaka klien ke layanan Azure. Biasanya, log digunakan untuk men-debug atau mendiagnosis masalah komunikasi. Artikel ini menjelaskan pendekatan berikut untuk mengaktifkan pengelogan dengan Azure SDK untuk .NET:

Mengaktifkan pengelogan dengan metode bawaan
Mengonfigurasi pengelogan kustom
Memetakan ke pengelogan ASP.NET Core

Penting

Artikel ini berlaku untuk pustaka klien yang menggunakan versi terbaru Azure SDK untuk .NET. Untuk melihat apakah pustaka didukung, lihat daftar rilis terbaru Azure SDK. Jika aplikasi Anda menggunakan versi pustaka klien Azure SDK yang lebih lama, lihat instruksi tertentu dalam dokumentasi layanan yang berlaku.

Informasi log

SDK mencatat setiap permintaan dan respons HTTP, membersihkan kueri parameter dan nilai header untuk menghapus data pribadi.

Entri log permintaan HTTP:

ID Unik
Metode HTTP
URI
Header permintaan keluar

Entri log respons HTTP:

Durasi operasi I/O (waktu yang berlalu)
ID permintaan
Kode status HTTP
Frasa alasan HTTP
Header respons
Informasi kesalahan, jika berlaku

Konten permintaan dan respons HTTP:

Aliran konten sebagai teks atau byte bergantung pada header Content-Type.

Catatan

Pengelogan konten dinonaktifkan secara default. Untuk mengaktifkannya, lihat Mencatat permintaan HTTP dan isi respons. Kemampuan ini hanya berlaku untuk pustaka menggunakan HTTP untuk berkomunikasi dengan layanan Azure. Pustaka berdasarkan protokol alternatif, seperti AMQP, tidak mendukung pengelogan konten. Contoh yang tidak didukung termasuk pustaka untuk layanan Azure seperti Azure Event Hubs, Bus Layanan, dan Web PubSub.

Log peristiwa adalah output biasanya di salah satu dari tiga tingkat ini:

Informasi untuk peristiwa permintaan dan respons
Peringatan untuk kesalahan
Verbose untuk pesan terperinci dan pengelogan konten

Mengaktifkan pengelogan dengan metode bawaan

Pustaka klien Azure SDK untuk .NET mencatat peristiwa ke Pelacakan Peristiwa untuk Windows (ETW) melalui kelas System.Diagnostics.Tracing.EventSource, yang umum untuk .NET. Sumber peristiwa memungkinkan Anda menggunakan pengelogan terstruktur di aplikasi Anda dengan overhead performa minimal. Untuk mendapatkan akses ke log peristiwa, Anda perlu mendaftarkan listener peristiwa.

SDK mencakup kelas Azure.Core.Diagnostics.AzureEventSourceListener, yang berisi dua metode statik yang menyederhanakan pengelogan komprehensif untuk aplikasi .NET Anda: CreateConsoleLogger dan CreateTraceLogger. Masing-masing metode ini menerima parameter opsional yang menentukan tingkat log. Jika parameter tidak disediakan, tingkat Informational log default digunakan.

Mencatat ke jendela konsol

Prinsip inti pustaka klien Azure SDK untuk .NET adalah menyederhanakan kemampuan untuk melihat log komprehensif secara real time. Metode CreateConsoleLogger memungkinkan Anda mengirim log ke jendela konsol dengan satu baris kode:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Mencatat ke pelacakan diagnostik

Jika Anda menerapkan listener pelacakan, Anda dapat menggunakan metode CreateTraceLogger untuk mencatat ke mekanisme pelacakan peristiwa .NET standar (System.Diagnostics.Tracing). Untuk informasi selengkapnya tentang pelacakan peristiwa di .NET, lihat Listener Pelacakan.

Contoh ini menentukan tingkat log verbose:

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

Mengonfigurasi pengelogan kustom

Seperti disebutkan di atas, Anda perlu mendaftarkan listener peristiwa untuk menerima pesan log dari Azure SDK untuk .NET. Jika Anda tidak ingin menerapkan pengelogan komprehensif menggunakan salah satu metode yang disederhanakan di atas, Anda dapat membuat instans AzureEventSourceListener kelas. Teruskan instans tersebut metode panggilan balik yang Anda tulis. Metode ini akan menerima pesan log yang dapat Anda proses sesuai kebutuhan Anda. Selain itu, saat membuat instans, Anda dapat menentukan tingkat log yang akan disertakan.

Contoh berikut membuat listener peristiwa yang mencatat ke konsol dengan pesan kustom. Log difilter ke peristiwa yang dipancarkan dari pustaka klien Azure Core dengan tingkat verbose. Pustaka Azure Core menggunakan nama sumber peristiwa 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);

Memetakan ke pengelogan ASP.NET Core

Layanan AzureEventSourceLogForwarder memungkinkan Anda menggunakan konfigurasi pengelogan ASP.NET Core standar untuk pengelogan. Layanan meneruskan pesan log dari sumber peristiwa Azure SDK ke ILoggerFactory.

Tabel berikut ini menggambarkan bagaimana EventLevel Azure SDK untuk .NET memetakan ke LogLevel ASP.NET Core.

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

Pengelogan dengan pendaftaran klien

Menggunakan pustaka Azure Bus Layanan sebagai contoh, selesaikan langkah-langkah berikut:

Instal paket Microsoft.Extensions.Azure NuGet:

dotnet add package Microsoft.Extensions.Azure

Di Program.cs, daftarkan klien pustaka Azure SDK melalui panggilan ke AddAzureClients metode ekstensi:
```
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());
});
```
Dalam sampel sebelumnya, AddAzureClients metode :
- Mendaftarkan objek berikut dengan kontainer injeksi dependensi (DI):
  - Layanan penerus log
  - Klien Azure Bus Layanan
- Mengatur kredensial token default yang akan digunakan untuk semua klien terdaftar.
Di appsettings.json, ubah tingkat log default pustaka Bus Layanan. Misalnya, alihkan ke Debug dengan mengatur kunci Logging:LogLevel:Azure.Messaging.ServiceBus sebagai berikut:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Karena kunci Logging:LogLevel:Azure.Messaging.ServiceBus diatur ke Debug, peristiwa klien Bus Layanan hingga EventLevel.Verbose akan dicatat.

Pengelogan tanpa pendaftaran klien

Ada skenario di mana mendaftarkan klien pustaka Azure SDK dengan kontainer DI tidak mungkin atau tidak perlu:

Pustaka Azure SDK tidak menyertakan IServiceCollection metode ekstensi untuk mendaftarkan klien dalam kontainer DI.
Aplikasi Anda menggunakan pustaka ekstensi Azure yang bergantung pada pustaka Azure SDK lainnya. Contoh pustaka ekstensi Azure tersebut meliputi:

Dalam skenario ini, selesaikan langkah-langkah berikut:

Instal paket Microsoft.Extensions.Azure NuGet:

dotnet add package Microsoft.Extensions.Azure

Di Program.cs, daftarkan layanan penerus log sebagai singleton dalam kontainer DI:

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

Ambil layanan penerus log dari kontainer DI dan panggil metodenya Start . Misalnya, menggunakan injeksi konstruktor di kelas model halaman ASP.NET Core Razor Pages:

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

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

Di appsettings.json, ubah tingkat log default pustaka Azure Core. Misalnya, alihkan ke Debug dengan mengatur kunci Logging:LogLevel:Azure.Core sebagai berikut:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Karena kunci Logging:LogLevel:Azure.Core diatur ke Debug, peristiwa pustaka Azure Core hingga EventLevel.Verbose akan dicatat.

Untuk informasi selengkapnya, lihat Pengelogan .NET Core dan ASP.NET Core.

Pengelogan menggunakan Azure.Monitor.OpenTelemetry.AspNetCore

Distro OpenTelemetry Azure Monitor, dimulai dengan versi 1.2.0, mendukung pengambilan log yang berasal dari pustaka klien Azure. Anda dapat mengontrol pengelogan menggunakan salah satu opsi konfigurasi yang dibahas dalam Pengelogan di .NET Core dan ASP.NET Core.

Menggunakan pustaka Azure Bus Layanan sebagai contoh, selesaikan langkah-langkah berikut:

Instal paket NuGet Azure.Monitor.OpenTelemetry.AspNetCore:

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

Membuat atau mendaftarkan klien pustaka. Distro mendukung kedua kasus.

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

Di appsettings.json, ubah tingkat log default pustaka Bus Layanan. Misalnya, alihkan ke Debug dengan mengatur kunci Logging:LogLevel:Azure.Messaging.ServiceBus sebagai berikut:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Karena kunci Logging:LogLevel:Azure.Messaging.ServiceBus diatur ke Debug, peristiwa klien Bus Layanan hingga EventLevel.Verbose akan dicatat.

Log badan permintaan dan respons HTTP

Catatan

Kemampuan ini hanya berlaku untuk pustaka menggunakan HTTP untuk berkomunikasi dengan layanan Azure. Pustaka berdasarkan protokol alternatif, seperti AMQP, tidak mendukung pengelogan konten. Contoh yang tidak didukung termasuk pustaka untuk layanan Azure seperti Azure Event Hubs, Bus Layanan, dan Web PubSub.

Saat memecahkan masalah perilaku tak terduga dengan pustaka klien, sangat membantu untuk memeriksa item berikut:

Isi permintaan HTTP dikirim ke REST API layanan Azure yang mendasar.
Isi respons HTTP yang diterima dari REST API layanan Azure.

Secara default, pengelogan konten yang disebutkan di atas dinonaktifkan. Untuk mengaktifkan pengelogan badan permintaan dan respons HTTP, selesaikan langkah-langkah berikut:

Atur properti objek IsLoggingContentEnabled opsi klien ke true, dan teruskan objek opsi ke konstruktor klien. Misalnya, untuk mencatat permintaan dan respons HTTP untuk pustaka Rahasia Azure Key Vault:

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

Gunakan pendekatan pengelogan pilihan Anda dengan tingkat peristiwa/log verbose/debug atau yang lebih tinggi. Temukan pendekatan Anda dalam tabel berikut untuk instruksi tertentu.

Pendekatan	Petunjuk
Mengaktifkan pengelogan dengan metode bawaan	Teruskan `EventLevel.Verbose` atau `EventLevel.LogAlways` ke `AzureEventSourceListener.CreateConsoleLogger` atau `AzureEventSourceListener.CreateTraceLogger`
Mengonfigurasi pengelogan kustom	Atur `AzureEventSourceListener` parameter konstruktor kelas `level` ke `EventLevel.Verbose` atau `EventLevel.LogAlways`
Memetakan ke pengelogan ASP.NET Core	Tambahkan `"Azure.Core": "Debug"` ke appsettings.json

Langkah berikutnya

Mengaktifkan pembuatan logging diagnostik untuk aplikasi di Azure App Service
Tinjau opsi Audit dan pengelogan keamanan Azure
Pelajari cara bekerja dengan Log platform Azure
Baca selengkapnya tentang pengelogan dan pelacakan .NET