.NET용 클라이언트 라이브러리를 사용하여 클라이언트 쪽 로깅

아티클
06/27/2023

.NET용 Azure Storage 클라이언트 라이브러리(버전 2.1 이상)를 사용하면 표준 .NET 진단 인프라를 사용하여 .NET 클라이언트 애플리케이션 내에서 Azure Storage 요청을 기록할 수 있습니다. 이러한 방식으로 클라이언트가 Azure Storage 서비스로 보내는 요청 및 수신된 응답에 대한 세부 정보를 볼 수 있습니다.

Azure Storage 클라이언트 라이브러리를 사용하면 기록할 수 있는 스토리지 요청을 제어할 수 있으며 .NET 진단 인프라를 사용하면 로그 데이터를 보낼 위치와 같은 로그 데이터를 완전히 제어할 수 있습니다. 예를 들어 처리를 위해 로그 데이터를 파일 또는 애플리케이션으로 보내도록 선택할 수 있습니다. Azure 스토리지 분석 및 네트워크 모니터링과 함께 클라이언트 라이브러리 로깅을 사용하여 애플리케이션이 Azure Storage 서비스와 상호 작용하는 방식에 대한 자세한 그림을 작성할 수 있습니다. 자세한 내용은 Azure Storage 모니터링, 진단 및 문제 해결을 참조하세요.

클라이언트 라이브러리 로깅을 사용하도록 설정하는 방법

다음 예제에서는 저장소 로그 메시지를 수집하여 텍스트 파일에 유지하는 데 필요한 system.diagnostics 구성을 보여 줍니다. 구성 섹션을 app.config 또는 web.config 파일에 추가할 수 있습니다.

참고

10.0.0 이전 버전을 사용하는 경우 대신 Microsoft.Azure.Storage이름을 Microsoft.WindowsAzure.Storage 사용합니다.

<system.diagnostics>  
     <!--In a dev/test environment you can set autoflush to true in order to autoflush to the log file. -->  
  <trace autoflush="false">  
    <listeners>  
      ...
      <add name="storageListener" />  
    </listeners>  
  </trace>  
  <sources>  
    <source name="Microsoft.Azure.Storage">  
      <listeners>  
        <add name="storageListener"/>  
      </listeners>  
    </source>  
  </sources>  
  <switches>  
    <add name="Microsoft.Azure.Storage" value="Verbose" />  
  </switches>  
  <sharedListeners>  
    <add name="storageListener"  
      type="System.Diagnostics.TextWriterTraceListener"  
      initializeData="C:\logs\WebRole.log"
      traceOutputOptions="DateTime" />  
  </sharedListeners>  
</system.diagnostics>

참고

버전 4.6.1-4.7.1(포함)의 .NET Framework 사용자는 Visual Studio의 NuGet 패키지 관리자가 자동으로 선택할 수 있는 Azure Storage 라이브러리의 .NET Standard 2.0 아티팩트를 사용할 때 로깅 문제가 발생할 수 있습니다. 라이브러리는 .NET Framework 4.5.2 아티팩트로도 게시되며, 이러한 문제가 발생하지 않습니다. 자세한 내용은 .NET Standard 버전 지원을 참조하세요.

이 예제에서는 실제 파일에 C:\logs\WebRole.log로그 메시지를 쓰도록 클라이언트 라이브러리를 구성합니다. EventLogTraceListener와 같은 다른 추적 수신기를 사용하여 Windows 이벤트 로그에 쓰거나 EventProviderTraceListener를 사용하여 ETW 하위 시스템에 추적 데이터를 쓸 수도 있습니다.

중요

로그 파일의 전체 폴더 경로는 로컬 파일 시스템에 있어야 합니다. 이 예제에서는 해당 폴더의 파일에 로그를 C:\logs 쓰기 전에 먼저 폴더를 만들어야 합니다.

또한 로그 항목을 버퍼링하는 대신 파일에 즉시 쓰기 위해 autoflush 를 true로 설정할 수 있습니다. 이 설정은 적은 양의 추적 메시지가 있는 개발/테스트 환경에서 유용할 수 있지만 프로덕션 환경에서 는 autoflush 를 false로 설정할 수 있습니다. 구성 설정을 사용하여 클라이언트의 모든 스토리지 작업에 대해 클라이언트 추적을 사용하도록 설정하고 모든 메시지에 대해 자세한 정보 표시와 같은 수준을 지정할 수 있습니다.

Id	로그 수준	이벤트
0	꺼짐	아무 것도 기록하지 않습니다.
1	오류	예외를 내부적으로 처리할 수 없고 사용자에게 throw되면 오류로 기록됩니다.
2	Warning	예외가 catch되어 내부적으로 처리되면 경고로 기록됩니다. 이 로그 수준의 기본 사용 사례는 재시도 시나리오입니다. 여기서 예외가 다시 시도하기 위해 사용자에게 다시 throw되지 않습니다. 이 동작은 404 오류가 자동으로 처리되는 CreateIfNotExists와 같은 작업에서도 발생할 수 있습니다.
3	정보 제공	다음 정보가 기록됩니다. •사용자가 메서드를 호출하여 작업을 시작한 직후 URI 및 클라이언트 요청 ID와 같은 요청 세부 정보가 기록됩니다. •요청 시작/종료 보내기, 데이터 업로드 시작/종료, 수신 응답 시작/종료, 데이터 시작/종료 다운로드와 같은 중요한 마일스톤이 기록되어 타임스탬프를 표시합니다. •헤더를 받은 직후 요청 ID 및 HTTP 상태 코드와 같은 응답 세부 정보가 기록됩니다. •작업이 실패하고 스토리지 클라이언트가 다시 시도하기로 결정한 경우 해당 결정의 이유는 다음 재시도 시기에 대한 정보와 함께 기록됩니다. •스토리지 클라이언트가 보류 중인 요청을 중단하기로 결정할 때 모든 클라이언트 쪽 시간 제한이 기록됩니다.
4	자세히	다음 정보가 기록됩니다. •각 요청에 대한 문자열-서명 •작업과 관련된 추가 세부 정보(정의 및 사용을 위한 각 작업까지).

기본적으로 클라이언트 라이브러리는 구성 파일에 지정한 세부 정보 수준에서 모든 스토리지 작업의 세부 정보를 기록합니다. 또한 로깅을 클라이언트 애플리케이션의 특정 영역으로 제한하여 기록된 데이터의 양을 줄이고 필요한 정보를 찾는 데 도움을 줄 수 있습니다. 로그에 기록된 데이터의 양을 제한하려면 클라이언트 애플리케이션에 일부 코드를 추가해야 합니다. 일반적으로 구성 파일에서 클라이언트 쪽 추적을 사용하도록 설정한 후 OperationContext 클래스를 사용하여 코드에서 전역적으로 해제합니다. 예를 들어 애플리케이션이 스토리지 작업을 수행하기 전에 Application_Start 메서드의 ASP.NET MVC 애플리케이션에서 이 작업을 수행할 수 있습니다.

protected void Application_Start()  
{  
    ...  
  
    // Disable Default Logging for Windows Azure Storage  
    OperationContext.DefaultLogLevel = LogLevel.Off;  
  
    // Verify that all of the tables, queues, and blob containers used in this application  
    // exist, and create any that don't already exist.  
    CreateTablesQueuesBlobContainers();  
}

그런 다음 로깅 수준을 정의하는 사용자 지정 OperationContext 개체를 만들어 관심 있는 특정 작업에 대해 추적을 사용하도록 설정할 수 있습니다. 그런 다음 다음 예제와 같이 스토리지 작업을 호출하는 데 사용하는 Execute 메서드에 OperationContext 개체를 매개 변수로 전달합니다.

[HttpPost]  
[ValidateAntiForgeryToken]  
public ActionResult Create(Subscriber subscriber)  
{  
    if (ModelState.IsValid)  
    {  
       ...  
        var insertOperation = TableOperation.Insert(subscriber);  
        OperationContext verboseLoggingContext = new OperationContext() { LogLevel = LogLevel.Verbose };  
        mailingListTable.Execute(insertOperation, null, verboseLoggingContext);  
        return RedirectToAction("Index");  
    }  
  
    ...  
    return View(subscriber);  
}

클라이언트 쪽 로그 스키마 및 샘플

다음 예제는 c3aa328b를 포함하는 클라이언트 요청 ID가 있는 작업을 위해 클라이언트 라이브러리에서 생성된 클라이언트 쪽 로그의 추출입니다. 클라이언트 요청 ID는 클라이언트 쪽에 기록된 메시지를 네트워크 추적 및 스토리지 로그와 상호 연결할 수 있는 상관 관계 식별자입니다. 상관 관계에 대한 자세한 내용은 Azure Storage 모니터링, 진단 및 문제 해결을 참조하세요. 추출된 부분에는 로그 파일 내에서 관찰할 수 있는 일부 핵심 정보에 대한 설명(기울임꼴로 들여쓴 부분)이 포함되어 있습니다.

다음 로그 파일의 첫 번째 행을 사용하여 이 기능을 설명하기 위해 필드는 다음과 같습니다.

로그 필드	값
원본	Microsoft.Azure.Storage
Verbosity	정보
자세한 정도 번호	3
클라이언트 요청 ID	c3aa328b...
작업 텍스트	위치 모드 PrimaryOnly에 대해 위치 Primary로 작업을 시작하는 중입니다.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
위의 추적 메시지는 위치 모드 가 기본으로만 설정되어 있음을 보여 하며, 이는 실패한 요청이 보조 위치로 전송되지 않음을 의미합니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
위의 추적 메시지는 요청이 동기적임을 보여줍니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
앞의 추적 메시지는 응답이 JSON 형식으로 반환되어야 한다는 것을 보여줍니다.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
위의 추적 메시지에는 인증 실패를 디버깅하는 데 유용한 StringToSign 정보가 포함됩니다. 자세한 메시지에는 작업 유형 및 요청 매개 변수를 비롯한 전체 요청 세부 정보도 포함됩니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
위의 추적 메시지는 요청이 전송되었고 클라이언트가 응답을 기다리고 있음을 보여줍니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
위의 추적 메시지는 응답이 수신되었으며 해당 http 상태 코드를 보여 주는 것입니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response headers were processed successfully, proceeding with the rest of the operation.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Processing response body.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Retrieved '8' results with continuation token ''.
위의 추적 메시지는 8개 결과가 검색되었고 연속 토큰이 제공되지 않음을 보여 하므로 이 쿼리에 대한 결과가 더 이상 없습니다.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
위의 추적 메시지는 작업이 성공적으로 완료되었음을 보여줍니다.

다음 두 개의 자세한 정보(수준 4) 로그 항목은 HEAD 및 DELETE 요청을 표시하고 작업 텍스트 필드의 자세한 정보를 보여 줍니다.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = HEAD............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:11 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = DELETE............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:12 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
위의 추적 메시지는 특정 요청과 관련된 자세한 정보를 포함하여 자세한 추적 메시지 내의 OperationText 필드를 보여줍니다. 이러한 세부 정보에는 HTTP 작업 유형(예: HEAD, DELETE, POST), 클라이언트 요청 ID, 타임스탬프, SDK 버전 및 추가 작업 관련 데이터가 포함됩니다.

.NET용 클라이언트 라이브러리를 사용하여 클라이언트 쪽 로깅

클라이언트 라이브러리 로깅을 사용하도록 설정하는 방법

클라이언트 쪽 로그 스키마 및 샘플

추가 리소스