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

NLog 是各種 .NET 平台 (包括 .NET Standard) 的彈性且免費的記錄平台。 NLog 可讓您寫入數個目標，例如資料庫、檔案或主機。 您可以使用 NLog 快速變更記錄設定。 NLog 接收器是 NLog 的目標，可讓您將記錄訊息傳送至 KQL 叢集。 外掛程式以 Azure-Kusto-Data 程式庫為建置基礎，並提供將記錄接收至叢集的有效方式。

在本文中，您將瞭解如何使用 nLog 接收內嵌數據。

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

必要條件

• .NET SDK 6.0 或更新版本
• Azure 數據總管 叢集和資料庫

設定您的環境

在本節中，您將準備環境以使用 NLog 連接器。

Install the package

新增 NLog.Azure.Kusto NuGet 套件。 使用 Install-Package 命令，指定 NuGet 套件的名稱。

Install-Package NLog.Azure.Kusto

建立 Microsoft Entra 應用程式註冊

Microsoft Entra 應用程式驗證用於需要存取平台且沒有使用者的應用程式。 若要使用 NLog 連接器取得資料，您必須建立並註冊 Microsoft Entra 服務主體，然後授權此主體從資料庫取得資料。

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

此服務主體將是連接器用來在 Kusto 資料表中寫入您的資料的識別。 您稍後會授與此服務主體存取 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 應用程式和服務主體。

儲存下列值以供後續步驟使用：*應用程式 (用戶端) ID * 目錄 (租用戶) ID * 用戶端密碼金鑰值

授與 Microsoft Entra 應用程式權限

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

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

   注意

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

建立資料表和擷取對應

建立傳入數據的目標數據表。

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

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

新增目標設定至您的應用程式

使用下列步驟，以便：

• 新增目標設定
• 建置並執行應用程式

1. 在 NLog 設定檔中新增目標。

   <targets>
       <target name="targettable" xsi:type="TargetTable"
       IngestionEndpointUri="<Connection string>"
       Database="<Database name>"
       TableName="<Table name>"
       ApplicationClientId="<Entra App clientId>"
       ApplicationKey="<Entra App key>"
       Authority="<Entra tenant id>"
       />
   </targets>
   
   ##Rules
   <rules>
       <logger name="*" minlevel="Info" writeTo="adxtarget" />
   </rules>
   

   如需更多選項，請參閱 Nlog 連接器。

2. 使用 NLog 接收器傳送資料。 例如：

   logger.Info("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   logger.Error(exceptionObj, "This was exception");
   logger.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
   logger.Warn("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
   

3. 建置並執行應用程式。 例如，如果您使用 Visual Studio，請按 F5。

4. 驗證資料在您的叢集中。 在您的查詢環境中，執行下列查詢，將預留位置取代為您稍早使用的資料表名稱：

   <TableName>
   | take 10
   

執行範例應用程式

使用樣本記錄產生器應用程式作為例子，示範如何設定和使用 NLog 接收器。

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

   git clone https://github.com/Azure/azure-kusto-nlog-sink.git
   

2. 設定下列環境變數，讓 NLog 設定檔可以立即從環境讀取它們：

   變數	描述
   INGEST_ENDPOINT	資料目標的擷取 URI。 您已在必要條件中複製此 URI。
   DATABASE	目標資料庫區分大小寫的名稱。
   APP_ID	驗證所需的應用程式用戶端識別碼。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。
   APP_KEY	驗證所需的應用程式金鑰。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。
   AZURE_TENANT_ID	在其中註冊應用程式的租用戶識別碼。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。

   您可以手動設定環境變數或使用下列命令：

   • Windows
   • Mac/Linux

   $env:INGEST_ENDPOINT="<ingestionURI>"
   $env:APP_ID="<appId>"
   $env:APP_KEY="<appKey>"
   $env:AZURE_TENANT_ID="<tenant>"
   $env:DATABASE="<databaseName>"
   

3. 在您的終端機內，瀏覽至複製的存放庫的根資料夾，然後執行下列 dotnet 命令來建置應用程式：

   cd .\NLog.Azure.Kusto.Samples\
   dotnet build
   

4. 在您的終端機中，瀏覽至範例資料夾並執行以下 dotnet 命令以執行應用程式：

   dotnet run
   

5. 在您的查詢環境中，選取目標資料庫，然後執行下列查詢來探索擷取的資料。

   ADXNLogSample
   | take 10
   

   您的輸出應該類似下列影像：

   

相關內容

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