.NET용 Azure SDK로 로깅

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

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

중요합니다

이 문서는 .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 서비스에 대한 라이브러리가 포함됩니다.

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

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

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

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

SDK에는 .NET 앱 Azure.Core.Diagnostics.AzureEventSourceListener 에 CreateConsoleLogger 대한 포괄적인 로깅을 간소화하는 두 가지 정적 메서드가 포함된 클래스가 포함됩니다CreateTraceLogger. 이러한 각 메서드는 로그 수준을 지정하는 선택적 매개 변수를 허용합니다. 매개 변수가 제공되지 않으면 기본 로그 수준이 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            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 확장 메서드 호출을 통해 Azure SDK 라이브러리의 클라이언트를 AddAzureClients 등록합니다.

   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.jsonService Bus 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 다음과 같이 키를 설정 Debug 하여 토글 Logging:LogLevel:Azure.Messaging.ServiceBus 합니다.

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

   Logging:LogLevel:Azure.Messaging.ServiceBus 키가 설정Debug되었으므로 Service Bus 클라이언트 이벤트가 최대 EventLevel.Verbose 로깅됩니다.

클라이언트 등록 없이 로깅

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.jsonAzure Core 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 다음과 같이 키를 설정 Debug 하여 토글 Logging:LogLevel:Azure.Core 합니다.

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

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

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

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

Azure Monitor OpenTelemetry 배포판은 버전1.2.0부터 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.jsonService Bus 라이브러리의 기본 로그 수준을 변경합니다. 예를 들어 다음과 같이 키를 설정 Debug 하여 토글 Logging:LogLevel:Azure.Messaging.ServiceBus 합니다.

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

   Logging:LogLevel:Azure.Messaging.ServiceBus 키가 설정Debug되었으므로 Service Bus 클라이언트 이벤트가 최대 EventLevel.Verbose 로깅됩니다.

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.VerboseEventLevel.LogAlways 또는 AzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger
   사용자 지정 로깅 구성	클래스의 AzureEventSourceListener 생성자 매개 변수를 levelEventLevel.VerboseEventLevel.LogAlways
   ASP.NET Core 로깅에 매핑	"Azure.Core": "Debug" 추가

다음 단계

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