使用 Serilog 接收將數據內嵌至 Azure 數據總管

Serilog 是適用於 .NET 應用程式的熱門紀錄架構， 可讓開發人員控制要輸出哪些記錄陳述式，而且可依記錄器名稱、記錄器層級與訊息模式等任意細微性進行輸出。 Serilog 接收也稱為附加程式，會將記錄數據串流至數據表，您可以在其中即時分析和可視化記錄。

本文說明如何使用 Serilog 內嵌數據。

如需數據連接器的完整清單，請參閱 數據整合概觀。

必要條件

• .NET SDK 6.0 或更新版本
• 具有預設快取和保留原則的 Azure 數據總 管叢集和資料庫 。
• Azure 數據總管查詢環境
• 格式叢集中 TargetURI 值的https://ingest-< Kusto 叢集> URI。<region.kusto.windows.net>。 如需詳細資訊，請參閱 新增叢集連線。

建立 Microsoft Entra 服務主體

Microsoft Entra 應用程式驗證用於需要存取 KQL 資料庫數據表且沒有使用者的應用程式。 若要使用 Serilog 連接器擷取數據，您必須建立並註冊Microsoft Entra 服務主體，然後授權此主體做為連接器用來將數據內嵌至 KQL 資料庫的身分識別。

Microsoft Entra 服務主體可以透過 Azure 入口網站 或以程序設計方式建立，如下列範例所示。

您稍後會授與此服務主體的許可權，以存取 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. 執行下列 .create 擷取對應命令，將佔位元 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 取代 AppId 為您在建立Microsoft Entra 服務主體時儲存的值。

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

在您的 ASP.NET Core 應用程式中使用 Serilog

本節說明如何將 Serilog 整合到您的 ASP.NET Core 應用程式，以記錄數據並將其傳送至 KQL 數據表。

Install the package

新增 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	驗證所需的應用程式用戶端識別碼。 您已在建立 Microsoft Entra 服務主體中儲存此值。
   AppKey	驗證所需的應用程式金鑰。 您已將此值儲存為password在建立Microsoft Entra 服務主體中。
   租用戶	註冊應用程式之租用戶的標識碼。 您已在建立 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	驗證所需的應用程式用戶端識別碼。 您已在建立 Microsoft Entra 服務主體中儲存此值。
   AppKey	驗證所需的應用程式金鑰。 您已在建立 Microsoft Entra 服務主體中儲存此值。
   租用戶	註冊應用程式之租用戶的標識碼。 您已在建立 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. 在您的終端機中，流覽至 samples 資料夾，然後執行下列 .NET 命令以執行應用程式：

   dotnet build run
   

3. 在查詢環境中，選取目標資料庫，然後執行下列查詢來探索擷取的數據，並以目標數據表的名稱取代佔位元 TableName ：

   <TableName>
   | take 10
   

   您的輸出看起來應該類似下圖：

   

相關內容

• 數據整合概觀
• Kusto 查詢語言 (KQL) 概觀