Serilog シンクを使用して Azure Data Explorer にデータを取り込む

Serilog は、.NET アプリケーションの一般的なログ記録フレームワークです。 Serilog を使用すると、開発者はロガーの名前、ロガーのレベル、メッセージパターンに基づいて任意の粒度で出力されるログステートメントを制御できます。アペンダーとも呼ばれる Serilog シンクは、ログデータをテーブルにストリーミングし、ユーザーはそこでログをリアルタイムで分析して視覚化できます。

この記事では、Serilog を使用してデータを取り込む方法について説明します。

データコネクタの完全な一覧については、「データ統合の概要」を参照してください。

前提条件

.NET SDK 6.0 以降
既定のキャッシュおよび保持ポリシーが設定された Azure Data Explorer クラスターおよびデータベース。
Azure Data Explorer クエリ環境
"clusterhttps://ingest-<.>region<.kusto.windows.net" のフォーマットで "TargetURI" 値に Kusto クラスター URI を指定します。> 詳細については、「クラスター接続の追加」を参照してください。

認証

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 データベースにデータを取り込むための ID としてこのプリンシパルを承認します。

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

プレースホルダー TableName をターゲットテーブル名に置き換え、TableNameMapping をインジェストマッピングの名前に置き換えて、次の .create ingestion mapping コマンドを実行します。

.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 ライブラリパッケージを追加します。 NuGet パッケージの名前を指定する Install-Package コマンドを使用します。

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。

環境変数は、手動で設定するか、次のコマンドを使用して設定できます。

ウィンドウズ
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

次の方法で共有

Serilog シンクを使用して Azure Data Explorer にデータを取り込む

前提条件

認証

Microsoft Entra サービス プリンシパルを作成する

ターゲット テーブルとインジェスト マッピングを作成する