次の方法で共有

Serilog からデータを取得する

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

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

データ コネクタの完全な一覧については、データ コネクタの概要に関する記事を参照してください。

前提条件

認証

Microsoft Entra 認証は、ユーザーが存在せずに KQL データベース テーブルにアクセスする必要があるアプリケーションに使用されます。 Serilog コネクタを使用してデータを取り込むには、次のいずれかの認証方法を使用できます。

  • Microsoft Entra サービス プリンシパルは、アプリケーションが特定の Azure リソースにアクセスするために使用するセキュリティ ID です。 この ID は、クライアント ID とパスワードを使用して KQL データベースへのコネクタを認証するために使用され、Azure の外部で実行されているアプリケーションに使用できます。

  • マネージド ID は、クライアント ID を使用して KQL データベースへのコネクタを認証するために使用されます。 マネージド ID は、Azure 内で実行されているアプリケーションに使用されます。

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

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. プレースホルダー 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 シンクを構成します。

    Microsoft Entra サービス プリンシパル認証では、次のコードを使用します。

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.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。

    その他のオプションについては、「シンク オプション」を参照してください。

  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 Microsoft Entra サービス プリンシパル認証に必要なアプリケーション クライアント ID。 この値は「Microsoft Entra サービス プリンシパルの作成」で保存しました。
    AppKey Microsoft Entra サービス プリンシパル認証に必要なアプリケーション キー。 この値は「Microsoft Entra サービス プリンシパルの作成」で保存しました。
    Tenant Microsoft Entra サービス プリンシパル認証を使用するときにアプリケーションが登録されるテナントの ID。 この値は「Microsoft Entra サービス プリンシパルの作成」で保存しました。
    BufferBaseFileName バッファー ファイルのベース ファイル名。 この値は、損失を発生させるクラスターへの接続の失敗に対する耐性をログに持たせる必要がある場合に設定します。 たとえば、C:/Temp/Serilog のように指定します。
    ManagedIdentityClientId マネージド ID 認証を使用する場合の、ユーザー割り当てマネージド ID のクライアント ID。

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

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

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

    dotnet build src

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

    dotnet build run

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

    <TableName>
| take 10

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

    タイムスタンプ レベル メッセージ 例外 プロパティ 配置 [経過時間]
    2023-03-12 1248:474590 情報 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 1248474770 警告 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 1248475590 エラー Zohar 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 1248474790 情報 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5610 警告 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5620 エラー Zohar 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5630 情報 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5660 エラー 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5670 情報 Zohar 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34
    2023-03-12 124847.5680 警告 処理済み { 緯度: 25、経度:30} {"位置": { "緯度": 25, "経度":30} { "緯度": 25, "経度":30} 34

関連するコンテンツ