รับข้อมูลด้วยตัวเชื่อมต่อ Apache log4J 2

2024-11-19

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

ลงชื่อเข้าใช้การสมัครใช้งาน Azure ของคุณผ่านทาง Azure CLI จากนั้นรับรองความถูกต้องในเบราว์เซอร์
```
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 ที่ส่งกลับ ให้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

ในสภาพแวดล้อมคิวรีของคุณ ให้เรียกใช้คําสั่งการจัดการต่อไปนี้ แทนชื่อฐานข้อมูลและ 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;

กําหนดค่าจม Log4j 2 โดยการเพิ่ม KustoStrategy รายการไปยังไฟล์ log4j2.xml แทนที่พื้นที่สํารองไว้โดยใช้ข้อมูลในตารางต่อไปนี้:

ตัวเชื่อมต่อ log4J 2 ใช้กลยุทธ์แบบกําหนดเองที่ใช้ใน RollingFileAppender บันทึกถูกเขียนลงในไฟล์ rolling เพื่อป้องกันข้อมูลสูญหายใด ๆ ที่เกิดขึ้นจากความล้มเหลวของเครือข่ายขณะเชื่อมต่อกับคลัสเตอร์ Kusto ข้อมูลถูกเก็บไว้ในไฟล์ rolling และจากนั้น ใส่ลงในคลัสเตอร์ 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	ingest URI สําหรับคลัสเตอร์ของคุณในคลัสเตอร์>รูปแบบhttps://ingest-<<region.kusto.windows.net>.
dbName	ชื่อแบบตรงตามตัวพิมพ์ใหญ่-เล็กของฐานข้อมูลเป้าหมาย
tableName	ชื่อที่ตรงตามตัวพิมพ์ใหญ่-เล็กของตารางเป้าหมายที่มีอยู่ ตัวอย่างเช่น Log4jTest คือชื่อของตารางที่สร้างขึ้นใน สร้างตาราง และการแมปการนําเข้า
appId	ID ไคลเอ็นต์ของแอปพลิเคชันที่จําเป็นสําหรับการรับรองความถูกต้อง คุณได้บันทึกค่านี้ใน สร้างการลงทะเบียนแอป Microsoft Entra
appKey	คีย์แอปพลิเคชันที่จําเป็นสําหรับการรับรองความถูกต้อง คุณได้บันทึกค่านี้ใน สร้างการลงทะเบียนแอป Microsoft Entra
appTenant	รหัสของผู้เช่าที่มีการลงทะเบียนแอปพลิเคชัน คุณได้บันทึกค่านี้ใน สร้างการลงทะเบียนแอป Microsoft Entra
logTableMapping	ชื่อของการแมป
mappingType	ชนิดของการแมปที่จะใช้ ค่าเริ่มต้นคือ csv
ล้างทั้งหมด	ถ้าตั้งค่าเป็น true อ่างล้างบัฟเฟอร์หลังจากแต่ละเหตุการณ์การบันทึก ค่าเริ่มต้นคือ เท็จ

สําหรับตัวเลือกเพิ่มเติม ดู ตัวเลือกจม

ส่งข้อมูลไปยัง 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);
  }
}

สร้างและเรียกใช้แอป
ตรวจสอบว่าข้อมูลอยู่ในคลัสเตอร์ของคุณ ในสภาพแวดล้อมคิวรีของคุณ ให้เรียกใช้คิวรีต่อไปนี้แทนที่ข้อความตัวอย่างด้วยชื่อของตารางที่ใช้ก่อนหน้านี้:
```
<TableName>
| take 10
```

เรียกใช้แอปตัวอย่าง

โคลน log4J 2 git repo โดยใช้คําสั่ง git ต่อไปนี้:
```
git clone https://github.com/Azure/azure-kusto-log4j.git
```
ตั้งค่าตัวแปรสภาพแวดล้อมต่อไปนี้เพื่อกําหนดค่าอ่างล้างหน้า Log4J 2:

หมายเหตุ

ในโครงการตัวอย่างที่รวมอยู่ใน git repo รูปแบบการกําหนดค่าเริ่มต้นจะถูกกําหนดไว้ใน 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>"
```
```
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>"
```
ในเทอร์มินัลของคุณ ให้นําทางไปยังโฟลเดอร์ตัวอย่างของ repo ที่ถูกโคลน และเรียกใช้คําสั่ง Maven ต่อไปนี้:
```
mvn compile exec:java -Dexec.mainClass="org.example.KustoLog4JSampleApp"
```
ในสภาพแวดล้อมคิวรีของคุณ ให้เลือกฐานข้อมูลเป้าหมายและเรียกใช้คิวรีต่อไปนี้เพื่อสํารวจข้อมูลที่นําเข้า แทนที่ TableName ของตัวแทนข้อความด้วยชื่อของตารางเป้าหมาย:
```
<TableName>
| take 10
```
เอาต์พุตของคุณควรมีลักษณะคล้ายกับตารางต่อไปนี้: