Pengelogan dengan Azure SDK untuk .NET

Azure SDK untuk .NET menyertakan pustaka klien yang memiliki kemampuan untuk mencatat operasi pustaka klien. Pengelogan ini memungkinkan Anda memantau permintaan dan respons I/O yang dibuat 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
Petakan 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 berlalu)
Nomor ID Permintaan
Kode Status HTTP
Frasa alasan HTTP
Tajuk respons
Informasi kesalahan, jika berlaku

Konten permintaan dan respons HTTP:

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

Nota

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 Event Hubs, Service Bus, dan Web PubSub.

Log peristiwa biasanya dihasilkan pada salah satu dari tiga tingkatan ini.

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

Mengaktifkan pengelogan dengan metode bawaan

Azure SDK untuk .NET menggunakan pustaka klien untuk mencatat peristiwa ke Pelacakan Peristiwa untuk Windows (ETW) melalui kelas System.Diagnostics.Tracing.EventSource, yang tipikal 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 pendengar peristiwa.

SDK mencakup Azure.Core.Diagnostics.AzureEventSourceListener kelas , yang berisi dua metode statis 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.

Masuk ke jendela konsol

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

using AzureEventSourceListener listener =
    AzureEventSourceListener.CreateConsoleLogger();

Catat ke dalam jejak diagnostik

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

Contoh ini menentukan tingkat log verbose:

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

Mengonfigurasi pengelogan kustom

Seperti disebutkan di atas, Anda perlu mendaftarkan pendengar 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. Berikan instans tersebut sebuah 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 pendengar acara yang mencatat ke konsol dengan pesan yang disesuaikan. 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Petakan ke pengelogan ASP.NET Core

Layanan ini 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 Azure SDK untuk .NET dipetakan ke 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 Service Bus sebagai contoh, selesaikan langkah-langkah berikut:

Instal paket Microsoft.Extensions.Azure NuGet:

dotnet add package Microsoft.Extensions.Azure

Di Program.cs, daftarkan klien dari pustaka Azure SDK melalui panggilan ke fungsi ekstensi AddAzureClients.
```
using Azure.Identity;
using Microsoft.Extensions.Azure;

// code omitted for brevity

builder.Services.AddAzureClients(azureBuilder =>
{
    azureBuilder.AddServiceBusClient(
        builder.Configuration.GetConnectionString("ServiceBus"));
});
```
Dalam sampel sebelumnya, metode AddAzureClients
- Mendaftarkan objek-objek berikut ke dalam kontainer dependensi injeksi (DI):
  - Layanan penerus log
  - Klien Azure Service Bus
- DefaultAzureCredential Berlaku secara otomatis untuk autentikasi kecuali kredensial yang berbeda dikonfigurasi secara eksplisit.
Di appsettings.json, ubah tingkat log default dari pustaka Service Bus. Misalnya, alihkan ke Debug dengan mengatur Logging:LogLevel:Azure.Messaging.ServiceBus kunci sebagai berikut:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Karena kunci telah diatur ke Debug, peristiwa klien Microsoft Azure Service Bus 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:

Azure SDK library tidak menyertakan metode ekstensi IServiceCollection untuk mendaftarkan klien dalam container 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 pada kelas model halaman di 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 level log bawaan dari pustaka Azure Core. Misalnya, alihkan ke Debug dengan mengatur Logging:LogLevel:Azure.Core kunci sebagai berikut:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Core Karena kunci telah diatur ke Debug, peristiwa library Azure Core hingga EventLevel.Verbose akan dicatat.

Untuk informasi selengkapnya, lihat Logging di .NET Core dan ASP.NET Core.

Pengelogan menggunakan Azure.Monitor.OpenTelemetry.AspNetCore

Azure Monitor OpenTelemetry distro, yang 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 Service Bus 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 Service Bus. Misalnya, alihkan ke Debug dengan mengatur Logging:LogLevel:Azure.Messaging.ServiceBus kunci sebagai berikut:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Karena kunci diatur ke Debug, peristiwa klien Service Bus hingga EventLevel.Verbose akan dicatat.

Log isi permintaan dan tanggapan HTTP

Nota

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 Event Hubs, Service Bus, dan Web PubSub.

Saat memecahkan masalah terkait perilaku tak terduga dengan pustaka klien, sangat membantu untuk memeriksa hal 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 pencatatan pilihan Anda dengan tingkat peristiwa/laporan log setidaknya verbose/debug atau 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`
Petakan ke pengelogan ASP.NET Core	Tambahkan `"Azure.Core": "Debug"` ke appsettings.json

Langkah selanjutnya

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-30