使用 Apache log4J 2 连接器引入数据

项目
09/09/2024

Log4J 是适用于 Java 应用程序的流行日志记录框架，由 Apache 基金会维护。开发人员可以使用 Log4J 根据记录器的名称、记录器级别和消息模式以任意粒度控制要输出的日志语句。 Apache Log4J 2 是 Log4J 的升级，与前面的 Log4j 1.x 相较，有了显著改进。 Log4J 2 提供了 Logback 中可用的许多改进，同时修复了 Logback 体系结构中的一些固有问题。 Apache log4J 2 接收器也称为追加器，可将你的日志数据流式传输到 Kusto 中的表，你可以在其中对日志进行实时分析和可视化。

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

先决条件

Apache Maven
一个 Azure 数据资源管理器群集和数据库

设置你的环境

在本部分，你将为环境使用 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 应用注册

通过 Azure CLI 登录到你的 Azure 订阅。然后在浏览器中进行身份验证。
```
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 应用程序和服务主体。

授予 Microsoft Entra 应用权限

在查询环境中，运行以下管理命令（将其中的占位符 DatabaseName 和 application ID 替换为之前保存的值）。此命令为应用授予数据库引入者角色。有关详细信息，请参阅管理数据库安全角色。
```
.add database DatabaseName ingestors ('aadappID=12345-abcd-12a3-b123-ccdd12345a1b') 'App Registration'
```
注意

最后一个参数是字符串，当查询与数据库关联的角色时，该字符串会显示为注释。有关详细信息，请参阅管理数据库角色。

创建表和引入映射

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

在查询编辑器中，运行以下表创建命令并将占位符 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)

运行以下引入映射命令，并将占位符 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 接收器添加到应用
配置接收器使用的变量
生成并运行应用

将以下代码添加到应用：

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

通过将 KustoStrategy 条目添加到 log4j2.xml 文件来配置 Log4j 2 接收器，使用下表中的信息替换占位符：

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"
/>

properties	说明
clusterIngestUrl	群集的引入 URI，格式为 https://ingest-<cluster>.<region>.kusto.chinacloudapi.cn。
dbName	目标数据库的名称，区分大小写。
tableName	现有目标表的名称，区分大小写。例如，Log4jTest 是在创建表和引入映射中创建的表的名称。
appId	用于身份验证的应用程序客户端 ID。在创建 Microsoft Entra 应用注册时你已保存此值。
appKey	用于身份验证的应用程序密钥。在创建 Microsoft Entra 应用注册时你已保存此值。
appTenant	应用程序注册到的租户的 ID。在创建 Microsoft Entra 应用注册时你已保存此值。
logTableMapping	映射的名称。
mappingType	要使用的映射的类型。默认值为 csv。
flushImmediately	如果设置为 true，接收器会在每个日志事件后刷新缓冲区。默认值为 false。

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

使用 Log4j 2 接收器将数据发送到 Kusto。例如：

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);
  }
}

生成并运行应用。
验证数据是否在群集中。在查询环境中，运行以下查询并将占位符替换为之前使用的表名称：
```
<TableName>
| take 10
```

运行示例应用

使用以下 git 命令克隆 log4J 2 git 存储库：

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

设置以下环境变量来配置 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.chinacloudapi.cn"
$env:LOG4J2_ADX_APP_ID="<app-id>"
$env:LOG4J2_ADX_APP_KEY="<app-key>"

export LOG4J2_ADX_DB_NAME="<db-name>"
export LOG4J2_ADX_TENANT_ID="<tenant-id>"
export LOG4J2_ADX_INGEST_CLUSTER_URL="https://ingest-<cluster>.kusto.chinacloudapi.cn"
export LOG4J2_ADX_APP_ID="<app-id>"
export LOG4J2_ADX_APP_KEY="<app-key>"

在终端中，导航到克隆的存储库的示例文件夹，然后运行以下 Maven 命令：
```
mvn compile exec:java -Dexec.mainClass="org.example.KustoLog4JSampleApp"
```
在查询环境中选择目标数据库，然后运行以下查询（将占位符 TableName 替换为目标表的名称）以浏览引入的数据：
```
<TableName>
| take 10
```
输出应类似于下表：

通过