使用 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 Data Explorer 叢集和資料庫或KQL 資料庫

設定環境

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

安裝套件

若要在應用程式中使用接收，請將下列相依性新增至 您的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 Entra 應用程式註冊

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

   屬性	Description
   clusterIngestUrl	格式https://ingest-<叢集中叢集>的內嵌URI。<region.kusto.windows.net>。
   dbName	目標資料庫的區分大小寫名稱。
   tableName	現有目標數據表的區分大小寫名稱。 例如， Log4jTest 是在 建立數據表和擷取對應中建立的數據表名稱。
   appId	驗證所需的應用程式用戶端識別碼。 您已在建立 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 Data Explorer Git 存放庫
• 使用 Log4j2 將 Azure Databricks 記錄擷取至 Azure Data Explorer - Azure Data Explorer 連接器社群部落格