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

Serilog 是适用于 .NET 应用程序的常用日志记录框架。 开发人员可以使用 Serilog 来根据记录器的名称、记录器级别和消息模式以任意粒度控制要输出哪些日志语句。 适用于 Azure 数据资源管理器的 Serilog 接收器（也称为追加器）将你的日志数据流式传输到 Azure 数据资源管理器，你可以在其中对日志进行实时分析和可视化。

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

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

先决条件

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

设置你的环境

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

安装包

添加 Serilog.Sinks.AzureDataExplorer NuGet 包。 使用 Install-Package 命令指定 NuGet 包的名称。

Install-Package Serilog.Sinks.AzureDataExplorer

创建 Microsoft Entra 应用注册

对于需要在未创建用户的情况下访问 Azure 数据资源管理器的应用程序，将使用 Microsoft Entra 应用程序身份验证。 若要使用 Serilog 连接器引入数据，需要创建并注册一个 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'
   

   注意

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

创建表和引入映射

为传入的数据创建目标表，将引入的数据列映射到目标表中的列。 在以下步骤中，表架构和映射对应于从示例应用发送的数据。

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();
   

   变量	说明
   IngestionEndPointUri	群集的引入 URI，格式为 https://ingest-<cluster>.<region>.kusto.chinacloudapi.cn。
   DatabaseName	目标数据库的名称，区分大小写。
   TableName	现有目标表的名称，区分大小写。 例如，SerilogTest 是在创建表和引入映射中创建的表的名称。
   AppId	用于身份验证的应用程序客户端 ID。 在创建 Microsoft Entra 应用注册时你已保存此值。
   AppKey	用于身份验证的应用程序密钥。 在创建 Microsoft Entra 应用注册时你已保存此值。
   租户	应用程序注册到的租户的 ID。 在创建 Microsoft Entra 应用注册时你已保存此值。
   BufferBaseFileName	缓冲区文件的可选基本文件名。 如果你要求日志持久保留，而不会因与群集连接失败而丢失，请设置此值。 例如，C:/Temp/Serilog。

   有关更多选项，请参阅接收器选项。

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

   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 接收器：

   变量	说明
   IngestionEndPointUri	群集的引入 URI，格式为 https://ingest-<cluster>.<region>.kusto.chinacloudapi.cn。
   DatabaseName	目标数据库的名称，区分大小写。
   TableName	现有目标表的名称，区分大小写。 例如，SerilogTest 是在创建表和引入映射中创建的表的名称。
   AppId	用于身份验证的应用程序客户端 ID。 在创建 Microsoft Entra 应用注册时你已保存此值。
   AppKey	用于身份验证的应用程序密钥。 在创建 Microsoft Entra 应用注册时你已保存此值。
   租户	应用程序注册到的租户的 ID。 在创建 Microsoft Entra 应用注册时你已保存此值。
   BufferBaseFileName	缓冲区文件的基本文件名。 如果你要求日志持久保留，而不会因与群集连接失败而丢失，请设置此值。 例如： C:/Temp/Serilog

   可以手动或使用以下命令设置环境变量：

   • Windows
   • Mac/Linux

   $env:ingestionURI="<ingestionURI>"
   $env:appId="<appId>"
   $env:appKey="<appKey>"
   $env:tenant="<tenant>"
   $env:databaseName="<databaseName>"
   $env:tableName="<tableName>"
   

3. 在终端中，导航到克隆的存储库的根文件夹，然后运行以下 .NET 命令以生成应用：

   dotnet build src
   

4. 在终端中，导航到 samples 文件夹，然后运行以下 .NET 命令以运行该应用：

   dotnet build run
   

5. 在 Web UI 中选择目标数据库，然后运行以下查询（将占位符 TableName 替换为目标表的名称）以浏览引入的数据：

   <TableName>
   | take 10
   

   输出应与下图类似：

   

相关内容

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