通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

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

本文介绍了如何使用 Serilog 来引入数据。

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

先决条件

身份验证

Microsoft Entra 身份验证用于需要访问 KQL 数据库表且没有用户存在的应用程序。 若要使用 Serilog 连接器引入数据，可以使用以下身份验证方法之一：

  • Microsoft Entra 服务主体是应用程序用来访问特定 Azure 资源的安全标识。 此标识用于使用客户端 ID 和密码对 KQL 数据库的连接器进行身份验证，并可用于在 Azure 外部运行的应用程序。

  • 托管身份用于通过客户端 ID 对 KQL 数据库的连接器进行身份验证。 托管标识用于在 Azure 中运行的应用程序。

创建 Microsoft Entra 服务主体

创建Microsoft Entra 服务主体，然后将此主体授权为连接器用于将数据引入 KQL 数据库的标识。

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

你稍后将授予此服务主体访问 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 应用程序和服务主体。

创建目标表和引入映射

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

  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}]'

  3. 根据创建 Microsoft Entra 服务主体授予服务主体数据库引入者角色，并提供使用数据库的权限。 有关详细信息，请参阅示例。 将占位符 DatabaseName 替换为目标数据库的名称，将 ApplicationID 替换为创建 Microsoft Entra 服务主体时保存的 AppId 值。

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

在 ASP.NET Core 应用程序中使用 Serilog

本部分介绍了如何将 Serilog 集成到 ASP.NET Core 应用程序中，以记录数据并将其发送到 KQL 表。

安装包

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

Install-Package Serilog.Sinks.AzureDataExplorer

将 Serilog 接收器添加到应用

使用以下步骤：

  • 将 Serilog 接收器添加到应用。
  • 配置接收器使用的变量。
  • 生成并运行应用。

  1. 将以下代码添加到应用：

    using Serilog.Sinks.AzureDataExplorer;

  2. 配置 Serilog 接收器，并使用后面的表中的信息替换占位符：

    对于Microsoft Entra 服务主体身份验证，请使用以下代码：

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();

    使用下表设置数据接收端选项的值：

    变量 说明
    IngestionEndPointUri 引入 URI。
    DatabaseName 目标数据库的名称，区分大小写。
    TableName 现有目标表的名称，区分大小写。 例如，SerilogTest 是在创建目标表和引入映射中创建的表的名称。
    AppId Microsoft Entra 服务主体身份验证所需的应用程序客户端 ID。 在创建 Microsoft Entra 服务主体中保存了此值。
    AppKey Microsoft Entra 服务主体身份验证所需的应用程序密钥。 在password中将此值保存为 。
    Tenant 使用 Microsoft Entra 服务主体身份验证时注册应用程序的租户 ID。 在创建 Microsoft Entra 服务主体中保存了此值。
    BufferBaseFileName 缓冲区文件的可选基本文件名。 如果你要求日志持久保留，而不会因与群集连接失败而丢失，请设置此值。 例如，C:/Temp/Serilog。
    ManagedIdentityClientId 使用托管标识身份验证时，用户分配的托管标识的客户端 ID。

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

  3. 使用 Serilog 接收器将数据发送到数据库。 例如：

    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. 验证数据是否在表中。 运行以下查询，将占位符替换为上一步中创建的表的名称：

    <TableName>
| take 10

运行示例应用

如果没有自己的数据要测试，则可以使用含示例数据的示例日志生成器应用来测试 Serilog 接收器的配置和使用。

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

    git clone https://github.com/Azure/serilog-sinks-azuredataexplorer

  2. 设置以下环境变量以配置 Serilog 接收器：

    变量 说明
    IngestionEndPointUri 引入 URI。
    DatabaseName 目标数据库的名称，区分大小写。
    TableName 现有目标表的名称，区分大小写。 例如，SerilogTest 是在创建目标表和引入映射中创建的表的名称。
    AppId Microsoft Entra 服务主体身份验证所需的应用程序客户端 ID。 在创建 Microsoft Entra 服务主体中保存了此值。
    AppKey Microsoft Entra 服务主体身份验证所需的应用程序密钥。 在创建 Microsoft Entra 服务主体中保存了此值。
    Tenant 使用 Microsoft Entra 服务主体身份验证时注册应用程序的租户 ID。 在创建 Microsoft Entra 服务主体中保存了此值。
    BufferBaseFileName 缓冲区文件的基本文件名。 如果你要求日志持久保留，而不会因与群集连接失败而丢失，请设置此值。 例如： C:/Temp/Serilog
    ManagedIdentityClientId 使用托管标识身份验证时，用户分配的托管标识的客户端 ID。

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

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

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

    dotnet build src

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

    dotnet build run

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

    <TableName>
| take 10

    输出应与下图类似：

    取 10 个函数和结果的表的屏幕截图。

相关内容