Прием данных с помощью приемника Serilog в Azure Data Explorer

Serilog — это популярная платформа ведения журнала для приложений .NET. Serilog позволяет разработчикам управлять выходными инструкциями журнала с произвольной степенью детализации на основе имени средства ведения журнала, уровня средства ведения журнала и шаблона сообщения. Приемник Serilog, также известный как аппендер, передает логовые данные в вашу таблицу, где можно анализировать и визуализировать логи в реальном времени.

В этой статье показано, как загружать данные с помощью Serilog.

Полный список соединителей данных см. в обзоре интеграции данных.

Предварительные условия

Пакет SDK для .NET версии 6.0 или более поздней версии
Кластер и база данных Azure Data Explorer с политиками кэша и хранения по умолчанию
Среда запросов Azure Data Explorer
URI кластера Kusto для значения TargetURI в формате https://ingest-<cluster>.<region>.kusto.windows.net. Дополнительные сведения см. в разделе Добавление подключения к кластеру.

Аутентификация

Проверка подлинности Microsoft Entra используется для приложений, чтобы получить доступ к таблице базы данных KQL без присутствия пользователя. Для приема данных с помощью соединителя Serilog можно использовать один из следующих методов проверки подлинности:

Служебная учётная запись Microsoft Entra — это идентификатор безопасности, используемый приложениями для доступа к определенным ресурсам Azure. Это удостоверение используется для проверки подлинности соединителя в базе данных KQL с помощью идентификатора клиента и пароля и может использоваться для приложений, работающих за пределами Azure.
Управляемое удостоверение используется для проверки подлинности соединителя в базе данных KQL с помощью идентификатора клиента. Управляемые удостоверения используются для приложений, работающих в облаке Azure.

Аутентификация служебного принципала Microsoft Entra
Проверка подлинности управляемого удостоверения

Создание учетной записи службы Microsoft Entra

Создайте служебную учетную запись Microsoft Entra и затем авторизуйте ее как удостоверение, используемое соединителем для загрузки данных в базу данных KQL.

Учетная запись службы Microsoft Entra может быть создана с помощью портала Azure или программно, как показано в примере ниже.

Позже вы предоставьте этому субъекту-службе разрешения для доступа к ресурсам Kusto.

Войдите в подписку Azure с помощью Azure CLI. Затем авторизуйтесь в браузере.
```
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 и учетную запись службы.

Создайте управляемое удостоверение

Создайте управляемую идентификацию и назначьте её в качестве идентификации, которой пользуется соединитель для отправки данных в базу данных KQL. Дополнительные сведения о создании управляемого удостоверения см. в статье "Управление управляемыми удостоверениями, назначенными пользователем".

Войдите в подписку Azure с помощью Azure CLI. Затем авторизуйтесь в браузере.
```
az login
```
Выберите подписку для размещения управляемого удостоверения. Этот шаг необходим, если у вас несколько подписок.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Назначьте управляемую сущность, назначаемую пользователем. В этом примере управляемое удостоверение называется my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Назначьте роль участника для области подписки управляемому удостоверению. В этом примере управляемое удостоверение называется my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

Скопируйте clientId из возвращаемых данных JSON для использования в будущем. Json имеет следующий формат:

{
  "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "id": "/subscriptions/00001111-aaaa-2222-bbbb-3333cccc4444/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-managed-identity",
  "location": "eastus",
  "name": "my-managed-identity",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "my-resource-group",
  "tags": {},
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Вы создали пользовательское управляемое удостоверение.

Создание целевой таблицы и сопоставления приема

Создайте целевую таблицу для входящих данных и схему сопоставления для отображения столбцов загруженных данных на столбцы в целевой таблице. В следующих шагах схема таблицы и сопоставление соответствуют данным, отправленным из примера приложения.

Выполните следующую команду создания таблицы в редакторе запросов, заменив заполнитель TableName именем целевой таблицы:
```
.create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)
```

Запустите следующую команду .create ingestion mapping, заменив 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}]'

Предоставьте служебному принципалу из создания Microsoft Entra разрешения роли ингестора базы данных для работы с базой данных. Дополнительные сведения см. в примерах. Замените заполнитель DatabaseName именем целевой базы данных и ApplicationID значением AppId , сохраненным при создании субъекта-службы Microsoft Entra.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Использование Serilog в приложении ASP.NET Core

В этом разделе объясняется, как интегрировать Serilog в приложение ASP.NET Core для регистрации данных и отправки его в таблицу KQL.

Установка пакета

Добавьте пакет библиотеки NuGet Serilog.Sinks.AzureDataExplorer . Используйте команду Install-Package, указывающую имя пакета NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Добавьте приемник Serilog в ваше приложение

Выполните следующие действия.

Добавьте приемник Serilog в приложение.
Настройте переменные, используемые приемником.
Выполните сборку и запустите приложение.

Добавьте в приложение следующий код:
```
using Serilog.Sinks.AzureDataExplorer;
```

Настройте приёмник Serilog, заменив заполнители информацией из таблицы ниже:

Аутентификация служебного принципала Microsoft Entra
Проверка подлинности управляемого удостоверения

Для аутентификации учетной записи службы Microsoft Entra используйте следующий код:

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

Для аутентификации с управляемой идентификацией используйте следующий код:

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

Используйте приведенную ниже таблицу, чтобы задать значения для параметров приемника:

«Переменная»	Описание
`IngestionEndPointUri`	URI ввода.
`DatabaseName`	Имя целевой базы данных с учетом регистра.
`TableName`	Имя существующей целевой таблицы с учетом регистра. Например, SerilogTest — это имя таблицы, которая создается в создании целевой таблицы и настройки маппинга для приёма данных.
`AppId`	Идентификатор клиента приложения, необходимый для проверки подлинности субъекта-службы Microsoft Entra. Вы сохранили это значение в "Создание учетной записи службы Microsoft Entra".
`AppKey`	Ключ приложения, необходимый для аутентификации служебного принципала Microsoft Entra. Это значение сохранено как `password` в процессе создания субъекта службы Microsoft Entra.
`Tenant`	Идентификатор тенанта, в котором зарегистрировано приложение при использовании проверки подлинности основного компонента Microsoft Entra. Вы сохранили это значение в "Создание учетной записи службы Microsoft Entra".
`BufferBaseFileName`	Необязательное имя базового файла для буферного файла. Задайте это значение, если требуется, чтобы журналы были устойчивы к потере данных в случае сбоев подключения к кластеру. Например, `C:/Temp/Serilog`.
`ManagedIdentityClientId`	Идентификатор клиента управляемой идентичности, назначенной пользователем, при использовании аутентификации управляемой идентичности.

Для более подробных параметров см. Параметры Sink.

Отправьте данные в базу данных с помощью приемника 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);

Выполните сборку и запустите приложение. Например, если вы используете Visual Studio, нажмите клавишу F5.
Убедитесь, что данные в вашей таблице. Выполните следующий запрос, заменив заполнитель именем таблицы, созданной на предыдущем шаге:
```
<TableName>
| take 10
```

Запуск примера приложения

Если у вас нет собственных данных для тестирования, можно использовать образец приложения-генератора журналов с образцами данных для проверки конфигурации и использования приемника Serilog.

Клонируйте репозиторий Git приемника Serilog с помощью следующей команды git:
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

Задайте следующие переменные среды для настройки приемника Serilog:

«Переменная»	Описание
`IngestionEndPointUri`	URI ввода.
`DatabaseName`	Имя целевой базы данных с учетом регистра.
`TableName`	Имя существующей целевой таблицы с учетом регистра. Например, SerilogTest — это имя таблицы, которая создается в создании целевой таблицы и настройки маппинга для приёма данных.
`AppId`	Идентификатор клиента приложения, необходимый для аутентификации служебного принципала Microsoft Entra. Вы сохранили это значение в "Создание учетной записи службы Microsoft Entra".
`AppKey`	Ключ приложения, необходимый для проверки подлинности учетной записи службы Microsoft Entra. Вы сохранили это значение в "Создание учетной записи службы Microsoft Entra".
`Tenant`	Идентификатор тенанта, в котором зарегистрировано приложение при использовании проверки подлинности основного компонента Microsoft Entra. Вы сохранили это значение в "Создание учетной записи службы Microsoft Entra".
`BufferBaseFileName`	Имя базового файла буфера. Задайте это значение, если требуется, чтобы журналы были устойчивы к потере данных в случае сбоев подключения к кластеру. Например: `C:/Temp/Serilog`
`ManagedIdentityClientId`	Идентификатор клиента управляемой идентичности, назначенной пользователем, при использовании аутентификации управляемой идентичности.

Переменные среды можно задать вручную или с помощью следующих команд:

Виндоус
Mac/Linux

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

export ingestionURI="<ingestionURI>"
export appId="<appId>"
export appKey="<appKey>"
export tenant="<tenant>"
export databaseName="<databaseName>"
export tableName="<tableName>"
export managedIdentityClientId="<managedIdentityClientId>"

В терминале перейдите к корневой папке клонированного репозитория и выполните следующую команду .NET, чтобы создать приложение:
```
dotnet build src
```
В терминале перейдите к папке примеров и выполните следующую команду .NET, чтобы запустить приложение:
```
dotnet build run
```

В среде запросов выберите целевую базу данных и выполните следующий запрос для анализа загруженных данных, заменив заполнитель TableName именем целевой таблицы:
```
<TableName>
| take 10
```
Выходные данные должны выглядеть примерно так:

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-25