使用 Apache log4J 2 連接器內嵌數據

Log4J 是 Apache Foundation 維護的 Java 應用程式的熱門記錄架構。 Log4J 可讓開發人員根據記錄器的名稱、記錄器層級和訊息模式，以任意數據粒度控制哪些記錄語句的輸出。 Apache Log4J 2 是 Log4J 的升級，先前的 Log4j 1.x 有顯著的改善。 Log4J 2 提供 Logback 中可用的許多改進功能，同時修正 Logback 架構中的一些固有問題。 Apache log4J 2 接收也稱為附加程式，會將記錄數據串流至 Kusto 中的數據表，您可以在其中即時分析和可視化記錄。

如需數據連接器的完整清單，請參閱 數據整合概觀。

必要條件

• Apache Maven
• Microsoft Fabric 中的 Azure 數據總管叢集和資料庫或 KQL 資料庫

設定您的環境

在本節中，您會準備環境以使用Log4J 2 接收。

Install the package

若要在應用程式中使用接收，請將下列相依性新增至 您的 pom.xml Maven 檔案。 接收預期 log4j核心 是以應用程式中的相依性的形式提供。

<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專案應用程式註冊

1. 透過 Azure CLI 登入您的 Azure 訂用帳戶。 然後在瀏覽器中進行驗證。

   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 數據中，複製 appId、 password和 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 應用程式和服務主體。

授與Microsoft Entra 應用程式許可權

1. 在您的查詢環境中，執行下列管理命令，以先前儲存的值取代佔位元 DatabaseName 和 應用程式識別碼 。 此命令會授與應用程式 資料庫擷取器 角色。 如需詳細資訊，請參閱 管理資料庫安全性角色。

   .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. 將專案新增 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"
   />
   

   屬性	說明
   clusterIngestUrl	叢集格式https://ingest-<>為叢集的內嵌URI。<region.kusto.windows.net>。
   dbName	目標資料庫的區分大小寫名稱。
   tableName	現有目標數據表的區分大小寫名稱。 例如，Log4jTest 是建立數據表和擷取對應中建立的數據表名稱。
   應用程式識別碼	驗證所需的應用程式用戶端識別碼。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。
   appKey	驗證所需的應用程式金鑰。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。
   appTenant	註冊應用程式之租用戶的標識碼。 您已在建立 Microsoft Entra 應用程式註冊中儲存此值。
   logTableMapping	對應的名稱。
   mappingType	要使用的對應類型。 預設值為 csv。
   flushImmediately	如果設定為 true，接收會在每個記錄事件之後排清緩衝區。 預設值為 false。

   如需更多選項，請參閱 接收選項。

3. 使用 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);
     }
   }
   

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

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

   Mac/Linux

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

3. 在您的終端機中，流覽至複製存放庫的samples資料夾，然後執行下列 Maven 命令：

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

4. 在您的查詢環境中，選取目標資料庫，然後執行下列查詢來探索內嵌的數據，並以目標數據表的名稱取代佔位元 TableName ：

   <TableName>
   | take 10
   

   您的輸出看起來應該類似下表：

   

相關內容

• 資料連接器概觀
• Kusto 查詢語言 (KQL) 概觀
• 開始使用 Azure Databricks Log4J 至 Azure 數據總管 Git 存放庫
• 使用 Log4j2 將 Azure Databricks 記錄內嵌至 Azure 數據總管 - Azure 數據總管連接器 社群部落格