.NET용 Azure SDK를 사용하여 로깅

.NET용 Azure SDK의 클라이언트 라이브러리에는 클라이언트 라이브러리 작업을 기록하는 기능이 포함되어 있습니다. 이 로깅을 사용하면 클라이언트 라이브러리가 Azure 서비스에 대해 수행하는 I/O 요청 및 응답을 모니터링할 수 있습니다. 일반적으로 로그는 통신 문제를 디버그하거나 진단하는 데 사용됩니다. 이 문서에서는 .NET용 Azure SDK를 사용하여 로깅을 사용하도록 설정하는 다음 방식을 설명합니다.

• 기본 제공 메서드를 사용하여 로깅 사용
• 사용자 지정 로깅 구성
• ASP.NET Core 로깅으로 매핑

Important

이 문서는 가장 최신 버전의 .NET용 Azure SDK를 사용하는 클라이언트 라이브러리에 적용됩니다. 라이브러리가 지원되는지 확인하려면 Azure SDK 최신 릴리스 목록을 참조하세요. 앱이 이전 버전의 Azure SDK 클라이언트 라이브러리를 사용하는 경우 해당 서비스 설명서의 특정 지침을 참조하세요.

로그 정보

SDK는 각 HTTP 요청과 응답을 기록하고 매개 변수 쿼리와 헤더 값을 삭제하여 개인 데이터를 제거합니다.

HTTP 요청 로그 항목:

• 고유 ID
• HTTP 메서드
• URI
• 나가는 요청 헤더

HTTP 응답 로그 항목:

• I/O 작업 기간(경과 시간)
• 요청 ID
• HTTP 상태 코드
• HTTP 이유 구문
• 응답 헤더
• 오류 정보(해당하는 경우)

HTTP 요청 및 응답 콘텐츠:

• Content-Type 헤더에 따라 텍스트 또는 바이트 형태의 콘텐츠 스트림입니다.

  참고 항목

  콘텐츠 로깅은 기본적으로 사용하지 않도록 설정됩니다. 이를 사용하도록 설정하려면 HTTP 요청 및 응답 본문 기록을 참조하세요. 이 기능은 HTTP를 사용하여 Azure 서비스와 통신하는 라이브러리에만 적용됩니다. AMQP와 같은 대체 프로토콜을 기반으로 하는 라이브러리는 콘텐츠 로깅을 지원하지 않습니다. 지원되지 않는 예로는 Event Hubs, Service Bus 및 Web PubSub와 같은 Azure 서비스용 라이브러리가 있습니다.

이벤트 로그는 일반적으로 다음 세 가지 수준 중 하나에서 출력됩니다.

• 요청 및 응답 이벤트에 대한 정보
• 오류에 대한 경고
• 자세한 메시지 및 콘텐츠 로깅에 대한 자세한 정보

기본 제공 메서드를 사용하여 로깅 사용

.NET용 Azure SDK의 클라이언트 라이브러리는 .NET에서 일반적인 System.Diagnostics.Tracing.EventSource 클래스를 통해 ETW(Windows용 이벤트 추적)에 이벤트를 로그합니다. 이벤트 원본을 사용하면 성능 오버헤드를 최소화하면서 앱에서 구조화된 로깅을 사용할 수 있습니다. 이벤트 로그에 대한 액세스 권한을 얻으려면 이벤트 수신기를 등록해야 합니다.

SDK에는 .NET 앱에 대한 포괄적인 로깅을 간소화하는 두 가지 정적 메서드인 CreateConsoleLogger 및 CreateTraceLogger가 포함된 Azure.Core.Diagnostics.AzureEventSourceListener 클래스가 포함되어 있습니다. 이러한 각 메서드는 로그 수준을 지정하는 선택적 매개 변수를 허용합니다. 매개 변수가 제공되지 않으면 기본 로그 수준인 Informational이 사용됩니다.

콘솔 창에 로그

.NET용 Azure SDK 클라이언트 라이브러리의 핵심 개념은 실시간으로 포괄적인 로그를 보는 기능을 간소화하는 것입니다. CreateConsoleLogger 메서드를 사용하면 한 줄의 코드로 로그를 콘솔 창에 보낼 수 있습니다.

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

진단 추적에 로그

추적 수신기를 구현하는 경우 CreateTraceLogger 메서드를 사용하여 표준 .NET 이벤트 추적 메커니즘(System.Diagnostics.Tracing)에 로그할 수 있습니다. .NET의 이벤트 추적에 대한 자세한 내용은 추적 수신기를 참조하세요.

이 예제에서는 자세한 로그 수준을 지정합니다.

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

사용자 지정 로깅 구성

위에서 설명한 것처럼 .NET용 Azure SDK에서 로그 메시지를 수신하려면 이벤트 수신기를 등록해야 합니다. 위의 간소화된 방법 중 하나를 사용하여 포괄적인 로깅을 구현하지 않으려면 AzureEventSourceListener 클래스의 인스턴스를 생성할 수 있습니다. 해당 인스턴스에 작성한 콜백 메서드를 전달합니다. 이 메서드는 처리할 수 있는 로그 메시지를 수신하지만 필요합니다. 또한 인스턴스를 생성할 때 포함할 로그 수준을 지정할 수 있습니다.

다음 예에서는 사용자 지정 메시지를 사용하여 콘솔에 기록하는 이벤트 수신기를 만듭니다. 로그는 자세한 수준으로 Azure Core 클라이언트 라이브러리에서 내보낸 이벤트로 필터링됩니다. Azure Core 라이브러리는 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);

ASP.NET Core 로깅으로 매핑

AzureEventSourceLogForwarder 서비스를 사용하면 로깅에 표준 ASP.NET Core 로깅 구성을 사용할 수 있습니다. 서비스는 Azure SDK 이벤트 원본의 로그 메시지를 ILoggerFactory로 전달합니다.

다음 표에서 .NET용 Azure SDK EventLevel이 ASP.NET Core LogLevel로 매핑되는 방식을 볼 수 있습니다.

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

클라이언트 등록으로 로깅

Azure Service Bus 라이브러리를 예로 사용하여 다음 단계를 완료합니다.

1. Microsoft.Extensions.Azure NuGet 패키지를 설치합니다.

   dotnet add package Microsoft.Extensions.Azure
   

2. Program.cs에서 AddAzureClients 확장 메서드 호출을 통해 Azure SDK 라이브러리의 클라이언트를 등록합니다.

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

   이전 샘플에서 AddAzureClients 메서드는 다음과 같습니다.

   • DI(종속성 주입) 컨테이너에 다음 개체를 등록합니다.
     • 로그 전달자 서비스
     • Azure Service Bus 클라이언트
   • 등록된 모든 클라이언트에 사용할 기본 토큰 자격 증명을 설정합니다.

3. appsettings.json에서 Service Bus 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 Logging:LogLevel:Azure.Messaging.ServiceBus 키를 다음과 같이 설정하여 Debug로 전환합니다.

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

   Logging:LogLevel:Azure.Messaging.ServiceBus 키는 Debug로 설정되어 있으므로 EventLevel.Verbose까지의 Service Bus 클라이언트 이벤트가 로그됩니다.

클라이언트 등록 없이 로깅

DI 컨테이너에 Azure SDK 라이브러리의 클라이언트를 등록하는 것이 불가능하거나 불필요한 시나리오가 있습니다.

• Azure SDK 라이브러리에는 DI 컨테이너에 클라이언트를 등록하기 위한 IServiceCollection 확장 메서드가 포함되어 있지 않습니다.
• 앱은 다른 Azure SDK 라이브러리에 의존하는 Azure 확장 라이브러리를 사용합니다. 이러한 Azure 확장 라이브러리의 예는 다음과 같습니다.
  • DataProtection용 Azure Key Vault 키 암호기
  • Azure Key Vault 비밀 구성 공급자
  • DataProtection을 위한 Azure Blob Storage 키 스토리지

이러한 시나리오에서는 다음 단계를 완료합니다.

1. Microsoft.Extensions.Azure NuGet 패키지를 설치합니다.

   dotnet add package Microsoft.Extensions.Azure
   

2. Program.cs에서 로그 전달자 서비스를 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());
   

3. DI 컨테이너에서 로그 전달자 서비스를 가져오고 해당 Start 메서드를 호출합니다. 예를 들어, ASP.NET Core Razor Pages 페이지 모델 클래스에서 생성자 주입을 사용하면 다음과 같습니다.

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

4. appsettings.json에서 Azure Core 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 Logging:LogLevel:Azure.Core 키를 다음과 같이 설정하여 Debug로 전환합니다.

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

   Logging:LogLevel:Azure.Core 키가 Debug로 설정되었으므로 최대 EventLevel.Verbose까지의 Azure Core 라이브러리 이벤트가 기록됩니다.

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅을 참조하세요.

Azure.Monitor.OpenTelemetry.AspNetCore를 사용하여 로깅

버전 1.2.0부터 Azure Monitor OpenTelemetry 배포판은 Azure 클라이언트 라이브러리에서 들어오는 로그 캡처를 지원합니다. .NET Core 및 ASP.NET Core 로깅에 설명된 구성 옵션을 사용하여 로깅을 제어할 수 있습니다.

Azure Service Bus 라이브러리를 예로 사용하여 다음 단계를 완료합니다.

1. Azure.Monitor.OpenTelemetry.AspNetCore NuGet 패키지를 설치합니다.

   dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
   

2. 라이브러리의 클라이언트를 만들거나 등록합니다. 배포판은 두 가지 경우를 모두 지원합니다.

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

3. appsettings.json에서 Service Bus 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 Logging:LogLevel:Azure.Messaging.ServiceBus 키를 다음과 같이 설정하여 Debug로 전환합니다.

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

   Logging:LogLevel:Azure.Messaging.ServiceBus 키는 Debug로 설정되어 있으므로 EventLevel.Verbose까지의 Service Bus 클라이언트 이벤트가 로그됩니다.

HTTP 요청 및 응답 본문 기록

참고 항목

이 기능은 HTTP를 사용하여 Azure 서비스와 통신하는 라이브러리에만 적용됩니다. AMQP와 같은 대체 프로토콜을 기반으로 하는 라이브러리는 콘텐츠 로깅을 지원하지 않습니다. 지원되지 않는 예로는 Event Hubs, Service Bus 및 Web PubSub와 같은 Azure 서비스용 라이브러리가 있습니다.

클라이언트 라이브러리의 예기치 않은 동작 문제를 해결할 때 다음 항목을 검사하는 것이 좋습니다.

• 기본 Azure 서비스의 REST API로 전송된 HTTP 요청 본문입니다.
• Azure 서비스의 REST API에서 수신된 HTTP 응답 본문입니다.

기본적으로 앞서 언급한 콘텐츠의 로깅은 사용하지 않도록 설정되어 있습니다. HTTP 요청 및 응답 본문의 로깅을 사용하도록 설정하려면 다음 단계를 완료합니다.

1. 클라이언트 옵션 개체의 IsLoggingContentEnabled 속성을 true로 설정하고 옵션 개체를 클라이언트 생성자에 전달합니다. 예를 들어, Azure Key Vault 비밀 라이브러리에 대한 HTTP 요청 및 응답을 기록하려면 다음을 수행합니다.

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

2. 이벤트/로그 수준이 상세/디버그 이상인 기본 로깅 방식을 사용합니다. 구체적인 지침은 다음 표에서 방식을 찾아보세요.

   접근 방식	지침
   기본 제공 메서드를 사용하여 로깅 사용	EventLevel.Verbose 또는 EventLevel.LogAlways를 AzureEventSourceListener.CreateConsoleLogger 또는 AzureEventSourceListener.CreateTraceLogger에 전달합니다.
   사용자 지정 로깅 구성	AzureEventSourceListener 클래스의 level 생성자 매개 변수를 EventLevel.Verbose 또는 EventLevel.LogAlways로 설정합니다.
   ASP.NET Core 로깅으로 매핑	appsettings.json에 "Azure.Core": "Debug" 추가

다음 단계

• Azure App Service에서 앱에 대한 진단 로깅 사용
• Azure 보안 로깅 및 감사 옵션 검토
• Azure 플랫폼 로그를 사용하는 방법 알아보기
• .NET 로깅 및 추적에 대해 자세히 알아봅니다.