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

NLog 是各種 .NET 平台的彈性且免費的記錄平臺，包括 .NET 標準。 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": "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 應用程式和服務主體。

儲存下列值，以供後續步驟使用：* 應用程式 （用戶端） 識別碼 * 目錄 （租使用者） 識別元 * 用戶端秘密密鑰值

授與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。
   資料庫	目標資料庫的區分大小寫名稱。
   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. 在您的終端機內，流覽至 samples 資料夾，然後執行下列 dotnet 命令以執行應用程式：

   dotnet run
   

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

   ADXNLogSample
   | take 10
   

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

   

相關內容

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