使用 NLog 接收器将数据引入 Azure 数据资源管理器

NLog 是一个灵活且免费的日志记录平台，适用于 .NET Standard 等各种 .NET 平台。 借助 NLog，可以写入多个目标，例如数据库、文件或控制台。 使用 NLog，可以即时更改日志记录配置。 NLog 接收器是 NLog 的目标，可用于将日志消息发送到 Azure 数据资源管理器群集。 该插件基于 Azure-Kusto-Data 库生成，提供了一种将日志汇聚到群集的有效方法。

本文将指导如何进行以下操作：

有关数据连接器的完整列表，请参阅数据连接器概述。

先决条件

• .NET SDK 6.0 或更高版本
• 一个 Azure 数据资源管理器群集和数据库

设置你的环境

在本部分，你将为环境使用 NLog 连接器做好准备。

安装包

添加 NLog.Azure.Kusto NuGet 包。 使用 Install-Package 命令指定 NuGet 包的名称。

Install-Package NLog.Azure.Kusto

创建 Microsoft Entra 应用注册

对于需要在未创建用户的情况下访问 Azure 数据资源管理器的应用程序，将使用 Microsoft Entra 应用程序身份验证。 若要使用 NLog 连接器引入数据，需要创建并注册一个 Microsoft Entra 服务主体，然后授权此主体将数据引入 Azure 数据资源管理器数据库。

1. 使用 Azure 数据资源管理器群集，按照在 Azure 数据资源管理器中创建 Microsoft Entra 应用程序注册中的步骤 1-7 进行操作。
2. 保存以下值以便在后续步骤中使用：
   • 应用程序（客户端）ID
   • 目录（租户）ID
   • 客户端机密密钥值

授予 Microsoft Entra 应用权限

1. 在 Web UI 的查询选项卡中连接到你的群集。 有关如何进行连接的详细信息，请参阅添加群集。

2. 浏览到要在其中引入数据的数据库。

3. 运行以下管理命令并替换占位符。 将 DatabaseName 替换为目标数据库的名称，将 ApplicationID 替换为之前保存的值。 此命令为应用授予数据库引入者角色。 有关详细信息，请参阅管理数据库安全角色。

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

   注意

   最后一个参数是字符串，当查询与数据库关联的角色时，该字符串会显示为注释。 有关详细信息，请参阅查看现有安全角色。

创建表和引入映射

为传入数据创建目标表。

• 在查询编辑器中，运行以下表创建命令并将占位符 TableName 替换为目标表的名称：

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

将 Azure 数据资源管理器目标配置添加到应用

使用以下步骤：

• 添加 Azure 数据资源管理器目标配置
• 生成并运行应用

1. 在 NLog 配置文件中添加 Azure 数据资源管理器目标。

   <targets>
       <target name="adxtarget" xsi:type="ADXTarget"
       IngestionEndpointUri="<ADX connection string>"
       Database="<ADX database name>"
       TableName="<ADX table name>"
       ApplicationClientId="<AAD App clientId>"
       ApplicationKey="<AAD App key>"
       Authority="<AAD tenant id>"
       />
   </targets>
   
   ##Rules
   <rules>
       <logger name="*" minlevel="Info" writeTo="adxtarget" />
   </rules>
   

   有关更多选项，请参阅 Azure 数据资源管理器 Nlog 连接器。

2. 使用 NLog 接收器将数据发送到 Azure 数据资源管理器。 例如：

   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. 验证数据是否在群集中。 在 Web UI 中，运行以下查询并将占位符替换为之前使用的表名称：

   <TableName>
   | take 10
   

运行示例应用

使用示例日志生成器应用作为示例，其中演示了如何配置和使用 NLog 接收器。

1. 使用以下 git 命令克隆 NLog 接收器的 git 存储库：

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

2. 设置以下环境变量，以便 NLog 配置文件可以立即从环境中读取它们：

   变量	说明
   INGEST_ENDPOINT	群集的引入 URI，格式为 https://ingest-<cluster>.<region>.kusto.chinacloudapi.cn。
   DATABASE	目标数据库的名称，区分大小写。
   APP_ID	用于身份验证的应用程序客户端 ID。 在创建 Microsoft Entra 应用注册时你已保存此值。
   APP_KEY	用于身份验证的应用程序密钥。 在创建 Microsoft Entra 应用注册时你已保存此值。
   AZURE_TENANT_ID	应用程序注册到的租户的 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. 在 Web UI 中选择目标数据库，然后运行以下查询以浏览引入的数据。

   ADXNLogSample
   | take 10
   

   输出应与下图类似：

   

相关内容

• 数据连接器概述
• Kusto 查询语言 (KQL) 概述