Serilog 싱크를 사용하여 Azure Data Explorer로 데이터 수집

Serilog는 .NET 애플리케이션에서 널리 사용되고 있는 로깅 프레임워크입니다. Serilog를 사용하면 개발자가 로거 이름, 로거 수준 및 메시지 패턴에 기반한 임의의 세분성을 사용하여 출력할 로그 문을 제어할 수 있습니다. 어펜더라고도 하는 Serilog 싱크는 로그 데이터를 테이블로 스트리밍하여 실시간으로 로그를 분석하고 시각화할 수 있습니다.

이 문서에서는 Serilog를 사용하여 데이터를 수집하는 방법을 보여줍니다.

데이터 커넥터의 전체 목록은 데이터 통합 개요를 참조하세요.

필수 조건

• .NET SDK 6.0 이상
• 기본 캐시 및 보존 정책을 사용하는 Azure Data Explorer 클러스터 및 데이터베이스 입니다.
• Azure Data Explorer 쿼리 환경
• 형식https://ingest-< 클러스터의 TargetURI 값에 대한 Kusto 클러스터> URI입니다.<region.kusto.windows.net>. 자세한 내용은 클러스터 연결 추가를 참조하세요.

Microsoft Entra 서비스 주체를 만듭니다.

Microsoft Entra 애플리케이션 인증은 사용자 없이 KQL 데이터베이스 테이블에 액세스해야 하는 애플리케이션에 사용됩니다. Serilog 커넥터를 사용하여 데이터를 수집하려면 Microsoft Entra 서비스 주체를 만들고 등록한 다음, 커넥터에서 KQL 데이터베이스로 데이터를 수집하는 데 사용하는 ID로 이 보안 주체에 권한을 부여해야 합니다.

Microsoft Entra 서비스 주체는 다음 예제와 같이 Azure Portal을 통하거나 프로그래밍 방식으로 만들 수 있습니다.

나중에 이 서비스 주체에 Kusto 리소스에 액세스할 수 있는 권한을 부여합니다.

1. Azure CLI를 통해 Azure 구독에 로그인합니다. 그런 다음 브라우저에서 인증합니다.

   az login
   

2. 서비스 주체를 호스트하는 구독을 선택합니다. 이 단계는 여러 구독이 있는 경우에 필요합니다.

   az account set --subscription YOUR_SUBSCRIPTION_GUID
   

3. 서비스 주체를 만듭니다. 이 예시에서는 서비스 주체를 my-service-principal이라고 합니다.

   az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}
   

4. 반환된 JSON 데이터에서 나중에 사용할 수 있도록 appId, password, tenant를 복사합니다.

   {
     "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
     "displayName": "my-service-principal",
     "name": "my-service-principal",
     "password": "00001111-aaaa-2222-bbbb-3333cccc4444",
     "tenant": "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
   

Microsoft Entra 애플리케이션과 서비스 주체를 만들었습니다.

대상 테이블 및 수집 매핑 만들기

대상 테이블의 맵에 수집된 데이터 열을 매핑하기 위해 수집 매핑 및 수신 데이터에 대한 대상 테이블을 만듭니다. 다음 단계에서 테이블 스키마 및 매핑은 샘플 앱에서 보낸 데이터에 해당합니다.

1. 쿼리 편집기에서 다음 테이블 만들기 명령을 실행합니다. 이때 자리 표시자 TableName을 대상 테이블의 이름으로 바꿉니다.

   .create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)
   

2. 다음 .create ingestion mapping 명령을 실행합니다. 이때 자리 표시자 TableName을 대상 테이블 이름으로, TableNameMapping을 수집 매핑의 이름으로 바꿉니다.

   .create table <TableName> ingestion csv mapping '<TableNameMapping>' '[{"Name":"Timestamp","DataType":"","Ordinal":"0","ConstValue":null},{"Name":"Level","DataType":"","Ordinal":"1","ConstValue":null},{"Name":"Message","DataType":"","Ordinal":"2","ConstValue":null},{"Name":"Exception","DataType":"","Ordinal":"3","ConstValue":null},{"Name":"Properties","DataType":"","Ordinal":"4","ConstValue":null},{"Name":"Position","DataType":"","Ordinal":"5","ConstValue":null},{"Name":"Elapsed","DataType":"","Ordinal":"6","ConstValue":null}]'
   

3. Microsoft Entra 서비스 주체 만들기 데이터베이스 수집자 역할 권한에서 서비스 주체에 데이터베이스 작업을 수행할 수 있는 권한을 부여합니다. 자세한 내용은 예제를 참조하세요. 자리 표시자 DatabaseName을 대상 데이터베이스의 이름으로 바꾸고 ApplicationID를 Microsoft Entra 서비스 주체를 만들 때 저장한 AppId 값으로 바꿉니다.

   .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
   

ASP.NET Core 애플리케이션에서 Serilog 사용

이 섹션에서는 Serilog를 ASP.NET Core 애플리케이션에 통합하여 데이터를 기록하고 KQL 테이블로 보내는 방법을 설명합니다.

패키지 설치

Serilog.Sinks.AzureDataExplorer NuGet 라이브러리 패키지를 추가합니다. Install-Package 명령을 사용합니다. 이때 NuGet 패키지의 이름을 지정합니다.

Install-Package Serilog.Sinks.AzureDataExplorer

앱에 Serilog 싱크 추가

다음 단계에 따라 다음을 수행합니다.

• Serilog 싱크를 앱에 추가합니다.
• 싱크에서 사용하는 변수를 구성합니다.
• 앱을 빌드하고 실행합니다.

1. 앱에 다음 코드를 추가합니다.

   using Serilog.Sinks.AzureDataExplorer;
   

2. Serilog 싱크를 구성합니다. 이때 다음 표의 정보를 사용하여 자리 표시자를 바꿉니다.

   var log = new LoggerConfiguration()
   .WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
   {
       IngestionEndpointUri = "<TargetURI>",
       DatabaseName = "<MyDatabase>",
       TableName = "<MyTable>",
       BufferBaseFileName = "<BufferBaseFileName>"
   })
   .CreateLogger();
   

   변수	설명
   IngestionEndPointUri	수집 URI.
   DatabaseName	대상 데이터베이스의 대/소문자 구분 이름입니다.
   TableName	기존 대상 테이블의 대/소문자 구분 이름. 예를 들어 SerilogTest는 대상 테이블 및 수집 매핑 만들기에서 만든 테이블의 이름입니다.
   AppId	인증에 필요한 애플리케이션 클라이언트 ID. Microsoft Entra 서비스 주체 만들기에서 이 값을 저장했습니다.
   AppKey	인증에 필요한 애플리케이션 키. Microsoft Entra 서비스 주체 만들기에서 이 값을 password로 저장했습니다.
   테넌트	애플리케이션이 등록된 테넌트 ID. Microsoft Entra 서비스 주체 만들기에서 이 값을 저장했습니다.
   BufferBaseFileName	버퍼 파일의 선택적 기본 파일 이름. 클러스터에 대한 연결 오류로 인해 손실이 발생한 경우 로그의 내구성을 유지해야 하는 경우 이 값을 설정합니다. 예들 들어 C:/Temp/Serilog입니다.

   자세한 옵션은 싱크 옵션을 참조하세요.

3. Serilog 싱크를 사용하여 데이터베이스로 데이터를 보냅니다. 예시:

   log.Verbose("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Warning("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Error(new Exception(), "Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
   

4. 앱을 빌드하고 실행합니다. 예를 들어 Visual Studio를 사용하는 경우 F5를 누릅니다.

5. 데이터가 테이블에 있는지 확인합니다. 다음 쿼리를 실행합니다. 이때 자리 표시자를 이전 단계에서 만든 테이블의 이름으로 바꿉니다.

   <TableName>
   | take 10
   

샘플 앱 실행

테스트할 자체 데이터가 없는 경우 Serilog 싱크의 사용 및 구성을 테스트하기 위해 샘플 데이터와 함께 샘플 로그 생성기 앱을 사용할 수 있습니다.

1. 다음 git 명령을 사용하여 Serilog 싱크의 git 리포지토리를 복제합니다.

   git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
   

2. Serilog 싱크를 구성하려면 다음 환경 변수를 설정합니다.

   변수	설명
   IngestionEndPointUri	수집 URI.
   DatabaseName	대상 데이터베이스의 대/소문자 구분 이름입니다.
   TableName	기존 대상 테이블의 대/소문자 구분 이름. 예를 들어 SerilogTest는 대상 테이블 및 수집 매핑 만들기에서 만든 테이블의 이름입니다.
   AppId	인증에 필요한 애플리케이션 클라이언트 ID. Microsoft Entra 서비스 주체 만들기에서 이 값을 저장했습니다.
   AppKey	인증에 필요한 애플리케이션 키. Microsoft Entra 서비스 주체 만들기에서 이 값을 저장했습니다.
   테넌트	애플리케이션이 등록된 테넌트 ID. Microsoft Entra 서비스 주체 만들기에서 이 값을 저장했습니다.
   BufferBaseFileName	버퍼 파일의 기본 파일 이름. 클러스터에 대한 연결 오류로 인해 손실이 발생한 경우 로그의 내구성을 유지해야 하는 경우 이 값을 설정합니다. 예를 들어 C:/Temp/Serilog

   이제 다음 명령을 사용하여 환경 변수를 수동으로 설정할 수 있습니다.

   Windows

   $env:ingestionURI="<ingestionURI>"
   $env:appId="<appId>"
   $env:appKey="<appKey>"
   $env:tenant="<tenant>"
   $env:databaseName="<databaseName>"
   $env:tableName="<tableName>"
   

   Mac/Linux

   export ingestionURI="<ingestionURI>"
   export appId="<appId>"
   export appKey="<appKey>"
   export tenant="<tenant>"
   export databaseName="<databaseName>"
   export tableName="<tableName>"
   

3. 터미널에서 복제된 리포지토리의 루트 폴더로 이동하고 다음 .NET 명령을 실행하여 앱을 빌드합니다.

   dotnet build src
   

4. 터미널에서 샘플 폴더를 찾은 후 다음 .NET 명령을 실행하여 앱을 실행합니다.

   dotnet build run
   

3. 쿼리 환경에서 대상 데이터베이스를 선택하고 다음 쿼리를 실행하여 수집된 데이터를 탐색하고 자리 표시자 TableName 을 대상 테이블의 이름으로 바꿉다.

   <TableName>
   | take 10
   

   출력은 다음 이미지와 비슷합니다.

   

관련 콘텐츠

• 데이터 통합 개요
• KQL(Kusto 쿼리 언어) 개요