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

Внимание

Этот соединитель можно использовать в аналитике в режиме реального времени в Microsoft Fabric. Используйте инструкции в этой статье со следующими исключениями:

• При необходимости создайте базы данных с помощью инструкций в статье "Создание базы данных KQL".
• При необходимости создайте таблицы с помощью инструкций в статье "Создание пустой таблицы".
• Получение URI запроса или приема с помощью инструкций в URI копирования.
• Выполнение запросов в наборе запросов KQL.

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

В этой статье вы узнаете, как выполнять следующие задачи.

• Настройка среды
• Добавление приемника Serilog в приложение
• Запуск примера приложения

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

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

• Пакет SDK для .NET версии 6.0 или более поздней версии
• Кластер и база данных Azure Data Explorer

Настройка среды

В этом разделе описана подготовка среды к использованию приемника Serilog.

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

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

Install-Package Serilog.Sinks.AzureDataExplorer

Создание регистрации приложения Microsoft Entra

Проверка подлинности приложения Microsoft Entra используется для приложений, которым требуется доступ к Azure Data Explorer без присутствующих пользователей. Чтобы принять данные с помощью соединителя Serilog, необходимо создать и зарегистрировать субъект-службу Microsoft Entra, а затем авторизовать этот субъект для приема данных базы данных Azure Data Explorer.

1. Используя кластер Azure Data Explorer, выполните действия 1-7 в статье "Создание регистрации приложения Microsoft Entra" в Azure Data Explorer.
2. Сохраните следующие значения, которые будут использоваться в последующих шагах:
   • Идентификатор приложения (клиент)
   • Идентификатор каталога (клиента)
   • Значение ключа секрета клиента

Предоставление разрешений приложения Microsoft Entra

1. На вкладке запроса веб-интерфейса подключитесь к кластеру. Дополнительные сведения о подключении см. в разделе "Добавление кластеров".

2. Перейдите к базе данных, в которой требуется принять данные.

3. Выполните следующую команду управления, заменив заполнители. Замените DatabaseName именем целевой базы данных и ApplicationID ранее сохраненным значением. Эта команда предоставляет приложению роль ingestor базы данных. Дополнительные сведения см. в разделе "Управление ролями безопасности базы данных".

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

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

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

3. Отправьте данные в Azure Data Explorer с помощью приемника 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. Клонируйте репозиторий приемника Serilog с помощью следующей команды Git:

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

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

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

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

   Windows

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

   Mac/Linux

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

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

   dotnet build src
   

4. В терминале перейдите в папку примеров и выполните следующую команду .NET, чтобы запустить приложение:

   dotnet build run
   

5. В пользовательском веб-интерфейсе выберите целевую базу данных и выполните следующий запрос, чтобы изучить прием данных, заменив заполнитель TableName именем целевой таблицы:

   <TableName>
   | take 10
   

   Выходные данные должны выглядеть примерно так:

   

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

• Обзор соединителей данных
• Обзор языка запросов Kusto (KQL)