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

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

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

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

필수 조건

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

인증

Microsoft Entra 인증은 사용자가 없는 KQL 데이터베이스 테이블에 액세스해야 하는 애플리케이션에 사용됩니다. Serilog 커넥터를 사용하여 데이터를 수집하려면 다음 인증 방법 중 하나를 사용할 수 있습니다.

Microsoft Entra 서비스 주체는 애플리케이션이 특정 Azure 리소스에 액세스하는 데 사용하는 보안 ID입니다. 이 ID는 클라이언트 ID 및 암호를 사용하여 KQL 데이터베이스에 대한 커넥터를 인증하는 데 사용되며 Azure 외부에서 실행되는 애플리케이션에 사용할 수 있습니다.
관리 ID는 클라이언트 ID를 사용하여 KQL 데이터베이스에 대한 커넥터를 인증하는 데 사용됩니다. 관리 ID는 Azure 내에서 실행되는 애플리케이션에 사용됩니다.

Microsoft Entra 서비스 주체 인증
관리 ID 인증

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

Microsoft Entra 서비스 주체 계정을 만들고, 이 주체를 KQL 데이터베이스에 데이터를 입력할 커넥터의 신원으로 권한을 부여합니다.

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

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

Azure CLI를 통해 Azure 구독에 로그인합니다. 그런 다음 브라우저에서 인증합니다.
```
az login
```
서비스 주체를 호스트하는 구독을 선택합니다. 이 단계는 여러 구독이 있는 경우에 필요합니다.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
서비스 주체를 만듭니다. 이 예시에서는 서비스 주체를 my-service-principal이라고 합니다.
```
az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}
```

반환된 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 애플리케이션과 서비스 주체를 만들었습니다.

관리 ID 만들기

관리 ID를 만들고 커넥터에서 KQL 데이터베이스에 데이터를 수집하는 데 사용하는 ID로 권한을 부여합니다. 관리 ID를 만드는 방법에 대한 자세한 내용은 사용자 할당 관리 ID 관리를 참조하세요.

Azure CLI를 통해 Azure 구독에 로그인합니다. 그런 다음 브라우저에서 인증합니다.
```
az login
```
관리 ID를 호스트할 구독을 선택합니다. 이 단계는 여러 구독이 있는 경우에 필요합니다.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
사용자 할당 관리형 ID를 만듭니다. 이 예제에서는 관리 ID를 호출 my-managed-identity합니다.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
구독 범위에 대한 기여자 역할을 관리 ID에 할당합니다. 이 예제에서는 관리 ID를 호출 my-managed-identity합니다.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

반환된 JSON 데이터에서 나중에 사용할 수 clientId 있는 데이터를 복사합니다. JSON의 형식은 다음과 같습니다.

{
  "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "id": "/subscriptions/00001111-aaaa-2222-bbbb-3333cccc4444/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-managed-identity",
  "location": "eastus",
  "name": "my-managed-identity",
  "principalId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "resourceGroup": "my-resource-group",
  "tags": {},
  "tenantId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

사용자가 할당한 관리 ID를 만들었습니다.

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

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

쿼리 편집기에서 다음 테이블 만들기 명령을 실행합니다. 이때 자리 표시자 TableName을 대상 테이블의 이름으로 바꿉니다.
```
.create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)
```

다음 .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}]'

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 싱크를 앱에 추가합니다.
싱크에서 사용하는 변수를 구성합니다.
앱을 빌드하고 실행합니다.

앱에 다음 코드를 추가합니다.
```
using Serilog.Sinks.AzureDataExplorer;
```

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

Microsoft Entra 서비스 주체 인증
관리 ID 인증

Microsoft Entra 서비스 주체 인증의 경우 다음 코드를 사용합니다.

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

관리 ID 인증의 경우 다음 코드를 사용합니다.

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

아래 표를 사용하여 싱크 옵션에 대한 값을 설정합니다.

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

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

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

앱을 빌드하고 실행합니다. 예를 들어 Visual Studio를 사용하는 경우 F5를 누릅니다.
데이터가 테이블에 있는지 확인합니다. 다음 쿼리를 실행합니다. 이때 자리 표시자를 이전 단계에서 만든 테이블의 이름으로 바꿉니다.
```
<TableName>
| take 10
```

샘플 앱 실행

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

다음 git 명령을 사용하여 Serilog 싱크의 git 리포지토리를 복제합니다.
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

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

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

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

Windows
Mac/Linux

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

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

터미널에서 복제된 리포지토리의 루트 폴더로 이동하고 다음 .NET 명령을 실행하여 앱을 빌드합니다.
```
dotnet build src
```
터미널에서 샘플 폴더를 찾은 후 다음 .NET 명령을 실행하여 앱을 실행합니다.
```
dotnet build run
```

쿼리 환경에서 대상 데이터베이스를 선택하고 다음 쿼리를 실행하여 수집된 데이터를 탐색하고 자리 표시자 TableName 을 대상 테이블의 이름으로 바꿉다.
```
<TableName>
| take 10
```
출력은 다음 이미지와 비슷합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-06-09