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

Статья
07/21/2024

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

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

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

Необходимые компоненты

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

Создание субъекта-службы Microsoft Entra

Проверка подлинности приложения Microsoft Entra используется для приложений, которым требуется доступ к таблице базы данных KQL без пользователя. Чтобы принять данные с помощью соединителя Serilog, необходимо создать и зарегистрировать субъект-службу 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 скопируйте appIdpasswordданные и tenant для дальнейшего использования.

{
  "appId": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
  "displayName": "my-service-principal",
  "name": "my-service-principal",
  "password": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
  "tenant": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn"
}

Вы создали приложение Microsoft Entra и субъект-службу.

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

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

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

Выполните следующую команду сопоставления приема и приема, заменив заполнители 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, заменив заполнители с помощью сведений в таблице, следующей:

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

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

Дополнительные параметры см. в разделе "Параметры приемника".

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

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

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

«Переменная»	Description
IngestionEndPointUri	URI приема.
DatabaseName	Имя целевой базы данных с учетом регистра.
TableName	Имя существующей целевой таблицы с учетом регистра. Например, SerilogTest — это имя таблицы, созданной в создании целевой таблицы и сопоставления приема.
AppId	Идентификатор клиента приложения, необходимый для проверки подлинности. Это значение сохранено в разделе "Создание субъекта-службы Microsoft Entra".
AppKey	Ключ приложения, необходимый для проверки подлинности. Это значение сохранено в разделе "Создание субъекта-службы Microsoft Entra".
Клиент	Идентификатор клиента, в котором зарегистрировано приложение. Это значение сохранено в разделе "Создание субъекта-службы 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>"

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

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

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

Поделиться через

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

Необходимые компоненты

Создание субъекта-службы Microsoft Entra

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

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

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

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

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

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

Дополнительные ресурсы

Поделиться через

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

Необходимые компоненты

Создание субъекта-службы Microsoft Entra

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

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

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

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

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

Связанный контент

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

Дополнительные ресурсы