使用 Serilog 接收將資料內嵌至 Azure Data Explorer

重要

此連接器可用於 Microsoft Fabric 中的 即時分析 。 使用本文中的指示，但有下列例外狀況：

• 如有需要，請使用 建立 KQL 資料庫中的指示來建立資料庫。
• 如有需要，請使用 建立空白資料表中的指示來建立資料表。
• 使用 複製 URI中的指示取得查詢或擷取 URI。
• 在 KQL 查詢集中執行查詢。

Serilog 是適用于 .NET 應用程式的常用記錄架構。 Serilog 可讓開發人員根據記錄器的名稱、記錄器層級和訊息模式，以任意資料細微性來控制哪些記錄語句是輸出的。 Serilog 接收也稱為附加器，適用于 Azure Data Explorer會將記錄資料串流至 Azure Data Explorer，您可以在其中即時分析和視覺化記錄。

在本文中，您將學會如何：

• 設定環境
• 將 Serilog 接收新增至您的應用程式
• 執行範例應用程式

如需資料連線器的完整清單，請參閱 資料連線器概觀。

必要條件

• .NET SDK 6.0 或更新版本
• Azure Data Explorer叢集和資料庫

設定環境

在本節中，您將準備環境以使用 Serilog 接收。

安裝套件

新增 Serilog.Sinks.AzureDataExplorer NuGet 套件。 使用指定 NuGet 套件名稱的 Install-Package 命令。

Install-Package Serilog.Sinks.AzureDataExplorer

建立Microsoft Entra應用程式註冊

Microsoft Entra應用程式驗證用於需要存取 Azure Data Explorer且沒有使用者的應用程式。 若要使用 Serilog 連接器擷取資料，您必須建立並註冊Microsoft Entra服務主體，然後授權此主體內嵌 Azure Data Explorer 資料庫的資料。

1. 使用 Azure Data Explorer 叢集，請遵循在 Azure Data Explorer中建立Microsoft Entra應用程式註冊中的步驟 1-7。
2. 儲存下列值，以供後續步驟使用：
   • 應用程式 (用戶端) 識別碼
   • 目錄 (租用戶) 識別碼
   • 用戶端秘密金鑰值

授與Microsoft Entra應用程式許可權

1. 在 Web UI的 [查詢] 索引標籤中，連線到您的叢集。 如需如何連線的詳細資訊，請參閱 新增叢集。

2. 流覽至您要在其中內嵌資料的資料庫。

3. 執行下列管理命令，取代預留位置。 將 DatabaseName 取代為目標資料庫的名稱，並將 ApplicationID 取代為先前儲存的值。 此命令會授與應用程式 資料庫擷取器 角色。 如需詳細資訊，請參閱 管理資料庫安全性角色。

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

   注意

   最後一個參數是一個字串，當您查詢與資料庫相關聯的角色時，會顯示為附注。 如需詳細資訊，請參閱 檢視現有的安全性角色。

建立資料表和擷取對應

建立傳入資料的目標資料表，並將內嵌的資料行對應至目標資料表中的資料行。 在下列步驟中，資料表架構和對應會對應至從範例應用程式傳送的資料。

1. 在查詢編輯器中，執行 下列資料表建立命令，以目標資料表的名稱取代預留位置 TableName ：

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

2. 執行下列 擷取對應命令，以目標資料表名稱取代 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}]'
   

將 Serilog 接收新增至您的應用程式

使用下列步驟：

• 將 Serilog 接收新增至您的應用程式
• 設定接收所使用的變數
• 建置並執行應用程式

1. 將下列程式碼新增至您的應用程式：

   using Serilog.Sinks.AzureDataExplorer;
   

2. 設定 Serilog 接收，並使用下列資料表中的資訊取代預留位置：

   var log = new LoggerConfiguration()
   .WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
   {
       IngestionEndpointUri = "<cluster>",
       DatabaseName = "<MyDatabase>",
       TableName = "<MyTable>",
       BufferBaseFileName = "<BufferBaseFileName>"
   })
   .CreateLogger();
   

   變數	Description
   IngestionEndPointUri	格式為叢集 > 的 https://ingest-< 擷取 URI。 <region.kusto.windows.net >。
   DatabaseName	目標資料庫的區分大小寫名稱。
   TableName	現有目標資料表的區分大小寫名稱。 例如， SerilogTest 是在 建立資料表和擷取對應中建立的資料表名稱。
   AppId	驗證所需的應用程式用戶端識別碼。 您已在[建立Microsoft Entra應用程式註冊] 中儲存此值。
   AppKey	驗證所需的應用程式金鑰。 您已在[建立Microsoft Entra應用程式註冊] 中儲存此值。
   租用戶	註冊應用程式的租使用者識別碼。 您已在[建立Microsoft Entra應用程式註冊] 中儲存此值。
   BufferBaseFileName	緩衝區檔案的選擇性基底檔案名。 如果您需要將記錄設為永久性，以免遺失導致叢集的連線失敗，請設定此值。 例如： C:/Temp/Serilog 。

   如需其他選項，請參閱 接收選項。

3. 使用 Serilog 接收將資料傳送至 Azure Data Explorer。 例如：

   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. 確認資料在您的叢集中。 在 Web UI中，執行下列查詢，以先前使用的資料表名稱取代預留位置：

   <TableName>
   | take 10
   

執行範例應用程式

使用範例記錄產生器應用程式作為示範如何設定和使用 Serilog 接收的範例。

1. 使用下列 git 命令複製 Serilog 接收的 Git 存放庫 ：

   git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
   

2. 設定下列環境變數以設定 Serilog 接收：

   變數	Description
   IngestionEndPointUri	格式為叢集 > 的 https://ingest-< 擷取 URI。 <region.kusto.windows.net >。
   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
   

5. 在 Web UI中，選取目標資料庫，然後執行下列查詢來探索擷取的資料，並將預留位置 TableName 取代為目標資料表的名稱：

   <TableName>
   | take 10
   

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

   

相關內容

• 資料連接器概觀
• Kusto 查詢語言 (KQL) 概觀