使用 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-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 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": "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 和 application ID。 此命令會授與應用程式資料庫擷取者角色。 如需詳細資訊，請參閱管理資料庫安全性角色。

   .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	叢集的擷取 URI，格式為 https://ingest-<cluster>.<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
   • 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 至 Azure 資料總管 Git 存放庫
• 使用 Log4j2 將 Azure Databricks 記錄內嵌至 Azure 數據總管 - Azure 數據總管連接器 社群部落格