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

项目
09/09/2024

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

本文介绍如何使用 nLog 接收器引入数据。

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

先决条件

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

设置你的环境

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

安装包

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

Install-Package NLog.Azure.Kusto

创建 Microsoft Entra 应用注册

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

Microsoft Entra 服务主体可以通过 Azure 门户或通过编程方式进行创建，如以下示例所示。

此服务主体将是连接器用于将数据写入到 Kusto 中的表的标识。你稍后将授予此服务主体访问 Kusto 资源所需的权限。

通过 Azure CLI 登录到你的 Azure 订阅。然后在浏览器中进行身份验证。
```
az login
```
选择要托管主体的订阅。当你有多个订阅时，此步骤是必需的。
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```

创建服务主体。在此示例中，服务主体名为 my-service-principal。

az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}

从返回的 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 应用权限

在你的查询环境中，运行以下管理命令并替换占位符。将 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)

将目标配置添加到应用

使用以下步骤：

添加目标配置
生成并运行应用

在 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 连接器。

使用 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);

生成并运行应用。例如，如果使用的是 Visual Studio，请按 F5。
验证数据是否在群集中。在查询环境中，运行以下查询并将占位符替换为之前使用的表名称：
```
<TableName>
| take 10
```

运行示例应用

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

使用以下 git 命令克隆 NLog 接收器的 git 存储库：
```
git clone https://github.com/Azure/azure-kusto-nlog-sink.git
```

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

变量	说明
INGEST_ENDPOINT	数据目标的引入 URI。已在先决条件中复制了此 URI。
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>"

export INGEST_ENDPOINT="<ingestionURI>"
export APP_ID="<appId>"
export APP_KEY="<appKey>"
export AZURE_TENANT_ID="<tenant>"
export DATABASE="<databaseName>"

在终端中，导航到克隆的存储库的根文件夹，然后运行以下 dotnet 命令以生成应用：
```
cd .\NLog.Azure.Kusto.Samples\
dotnet build
```
在终端中，导航到 samples 文件夹，然后运行以下 dotnet 命令以运行该应用：
```
dotnet run
```
在查询环境中选择目标数据库，然后运行以下查询以浏览引入的数据。
```
ADXNLogSample
| take 10
```
输出应与下图类似：

通过