使用 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": "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. 執行下列 .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}]'
   

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 程式庫套件。 使用 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	驗證所需的應用程式金鑰。 您已在建立 Microsoft Entra 服務主體中將此值儲存為 password。
   租用戶	在其中註冊應用程式的租用戶識別碼。 您已在建立 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
   • 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) 概觀