Прием данных с помощью соединителя Apache log4J 2

Log4J — это популярная платформа ведения журнала для приложений Java, поддерживаемых Apache Foundation. Log4J позволяет разработчикам управлять выходными инструкциями журнала с произвольной степенью детализации на основе имени средства ведения журнала, уровня ведения журнала и шаблона сообщения. Apache Log4J 2 — это обновление до Log4J с значительными улучшениями предыдущей версии Log4j 1.x. Log4J 2 предоставляет множество улучшений, доступных в Logback, при этом устраняя некоторые проблемы в архитектуре Logback. Приемник Apache log4J 2, также известный как добавление, передает данные журнала в таблицу Kusto, где можно анализировать и визуализировать журналы в режиме реального времени.

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

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

• Apache Maven
• Кластер и база данных Azure Data Explorer или база данных KQL в Microsoft Fabric

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

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

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

Чтобы использовать приемник в приложении, добавьте следующие зависимости в файл pom.xml Maven. Приемник ожидает , что log4j-core предоставляется в качестве зависимости в приложении.

<dependency>
    <groupId>com.microsoft.azure.kusto</groupId>
    <artifactId>azure-kusto-log4j</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>${log4j.version}</version>
</dependency>

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

1. Войдите в подписку Azure с помощью Azure CLI. Затем авторизуйтесь в браузере.

   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 скопируйте appIdpasswordданные и 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 и субъект-службу.

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

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

   .add database DatabaseName ingestors ('aadappID=12345-abcd-12a3-b123-ccdd12345a1b') 'App Registration'
   

   Примечание.

   Последний параметр — это строка, которая отображается в виде примечаний при запросе ролей, связанных с базой данных. Дополнительные сведения см. в разделе "Управление ролями базы данных".

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

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

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

   .create table log4jTest (timenanos:long,timemillis:long,level:string,threadid:string,threadname:string,threadpriority:int,formattedmessage:string,loggerfqcn:string,loggername:string,marker:string,thrownproxy:string,source:string,contextmap:string,contextstack:string)
   

2. Выполните следующую команду сопоставления приема, заменив заполнители TableName именем целевой таблицы и TableNameMapping именем сопоставления приема:

   .create table log4jTest ingestion csv mapping 'log4jCsvTestMapping' '[{"Name":"timenanos","DataType":"","Ordinal":"0","ConstValue":null},{"Name":"timemillis","DataType":"","Ordinal":"1","ConstValue":null},{"Name":"level","DataType":"","Ordinal":"2","ConstValue":null},{"Name":"threadid","DataType":"","Ordinal":"3","ConstValue":null},{"Name":"threadname","DataType":"","Ordinal":"4","ConstValue":null},{"Name":"threadpriority","DataType":"","Ordinal":"5","ConstValue":null},{"Name":"formattedmessage","DataType":"","Ordinal":"6","ConstValue":null},{"Name":"loggerfqcn","DataType":"","Ordinal":"7","ConstValue":null},{"Name":"loggername","DataType":"","Ordinal":"8","ConstValue":null},{"Name":"marker","DataType":"","Ordinal":"9","ConstValue":null},{"Name":"thrownproxy","DataType":"","Ordinal":"10","ConstValue":null},{"Name":"source","DataType":"","Ordinal":"11","ConstValue":null},{"Name":"contextmap","DataType":"","Ordinal":"12","ConstValue":null},{"Name":"contextstack","DataType":"","Ordinal":"13","ConstValue":null}]'
   

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

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

• Добавление приемника Log4j 2 в приложение
• Настройка переменных, используемых приемником
• Сборка и запуск приложения

1. Добавьте в приложение следующий код:

   package com.microsoft.azure.kusto.log4j.sample;
   import org.apache.logging.log4j.LogManager;
   import org.apache.logging.log4j.Logger;
   

2. Настройте приемник Log4j 2, добавив KustoStrategy запись в файл log4j2.xml, заменив заполнители с помощью сведений в таблице, следующей:

   Соединитель log4J 2 использует пользовательскую стратегию, используемую в RollingFileAppender. Журналы записываются в скользящий файл, чтобы предотвратить потерю данных из-за сбоя сети при подключении к кластеру Kusto. Данные хранятся в последовательном файле, а затем удаляются в кластер Kusto.

   <KustoStrategy
     clusterIngestUrl = "${env:LOG4J2_ADX_INGEST_CLUSTER_URL}"
     appId = "${env:LOG4J2_ADX_APP_ID}"
     appKey = "${env:LOG4J2_ADX_APP_KEY}"
     appTenant = "${env:LOG4J2_ADX_TENANT_ID}"
     dbName = "${env:LOG4J2_ADX_DB_NAME}"
     tableName = "<MyTable>"
     logTableMapping = "<MyTableCsvMapping>"
     mappingType = "csv"
     flushImmediately = "false"
   />
   

   Свойство	Description
   clusterIngestUrl	URI приема для кластера в кластере> форматаhttps://ingest-<.<region.kusto.windows.net>.
   dbName	Имя целевой базы данных с учетом регистра.
   tableName	Имя существующей целевой таблицы с учетом регистра. Например, Log4jTest — это имя таблицы, созданной в разделе "Создание таблицы и сопоставления приема".
   appId	Идентификатор клиента приложения, необходимый для проверки подлинности. Это значение сохранено в разделе "Создание регистрации приложения Microsoft Entra".
   appKey	Ключ приложения, необходимый для проверки подлинности. Это значение сохранено в разделе "Создание регистрации приложения Microsoft Entra".
   appTenant	Идентификатор клиента, в котором зарегистрировано приложение. Это значение сохранено в разделе "Создание регистрации приложения Microsoft Entra".
   logTableMapping	Имя сопоставления.
   mappingType	Тип используемого сопоставления. Значение по умолчанию — CSV.
   flushImmediately	Если задано значение true, приемник очищает буфер после каждого события журнала. Значение по умолчанию — false.

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

3. Отправьте данные в Kusto с помощью приемника Log4j 2. Например:

   import java.util.concurrent.Executors;
   import java.util.concurrent.ScheduledExecutorService;
   import java.util.concurrent.TimeUnit;
   
   public class MyClass {
     private static final Logger logger = LogManager.getLogger(KustoLog4JSampleApp.class);
     public static void main(String[] args) {
       Runnable loggingTask = () -> {
         logger.trace(".....read_physical_netif: Home list entries returned = 7");
         logger.debug(".....api_reader: api request SENDER");
         logger.info(".....read_physical_netif: index #0, interface VLINK1 has address 129.1.1.1, ifidx 0");
         logger.warn(".....mailslot_create: setsockopt(MCAST_ADD) failed - EDC8116I Address not available.");
         logger.error(".....error_policyAPI: APIInitializeError:  ApiHandleErrorCode = 98BDFB0,  errconnfd = 22");
         logger.fatal(".....fatal_error_timerAPI: APIShutdownError:  ReadBuffer = 98BDFB0,  RSVPGetTSpec = error");
       };
       ScheduledExecutorService executor = Executors.newScheduledThreadPool(1);
       executor.scheduleAtFixedRate(loggingTask, 0, 3, TimeUnit.SECONDS);
     }
   }
   

4. Выполните сборку и запустите приложение.

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

   <TableName>
   | take 10
   

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

1. Клонируйте репозиторий git log4J 2 с помощью следующей команды Git:

   git clone https://github.com/Azure/azure-kusto-log4j.git
   

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

   Примечание.

   В примере проекта, включенного в репозиторий Git, формат конфигурации по умолчанию определяется в файле log4j2.xml. Этот файл конфигурации находится в пути к файлу: \azure-kusto-log4j\samples\src\main\resources\log4j2.xml.

   • Windows
   • Mac/Linux

   $env:LOG4J2_ADX_DB_NAME="<db-name>"
   $env:LOG4J2_ADX_TENANT_ID="<tenant-id>"
   $env:LOG4J2_ADX_INGEST_CLUSTER_URL="https://ingest-<cluster>.kusto.windows.net"
   $env:LOG4J2_ADX_APP_ID="<app-id>"
   $env:LOG4J2_ADX_APP_KEY="<app-key>"
   

3. В терминале перейдите в папку примеров клонированного репозитория и выполните следующую команду Maven:

   mvn compile exec:java -Dexec.mainClass="org.example.KustoLog4JSampleApp"
   

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

   <TableName>
   | take 10
   

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

   

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

• Обзор соединителей данных
• Обзор языка запросов Kusto (KQL)
• Приступая к работе с репозиторием Azure Databricks Log4J в репозитории Git Azure Data Explorer
• Прием журналов Azure Databricks в Azure Data Explorer с помощью блога сообщества соединителей Azure Data Explorer Log4j2