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

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

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

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

前提条件

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

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": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
     "displayName": "my-service-principal",
     "name": "my-service-principal",
     "password": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
     "tenant": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn"
   }
   

Microsoft Entra アプリケーションとサービス プリンシパルが作成されました。

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

受信データのターゲット テーブルと、取り込まれたデータ列をターゲット テーブル内の列にマップするためのインジェスト マッピングを作成します。 以下の手順では、テーブル スキーマとマッピングは、サンプル アプリから送信されたデータに対応します。

1. プレースホルダー TableName をターゲット テーブルの名前に置き換えて、クエリ エディターで次のテーブル作成コマンドを実行します。

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

2. プレースホルダー 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}]'
   

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

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
   • Mac/Linux

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

3. ターミナルで、クローンされたリポジトリのルート フォルダーに移動し、次の .NET コマンドを実行してアプリをビルドします。

   dotnet build src
   

4. ターミナルで、サンプル フォルダーに移動し、次の .NET コマンドを実行してアプリを実行します。

   dotnet build run
   

3. クエリ環境で、ターゲット データベースを選択し、プレースホルダー TableName をターゲット テーブルの名前に置き換えて次のクエリを実行し、取り込まれたデータを調べます。

   <TableName>
   | take 10
   

   出力は、次の画像のようになります。

   

関連するコンテンツ

• データ統合の概要
• Kusto クエリ言語 (KQL) の概要