Erfassen von Daten mit dem Apache log4J 2-Connector
Log4J ist ein von der Apache Foundation unterstütztes beliebtes Protokollierungsframework für Java-Anwendungen. Mit Log4J können Entwickler steuern, welche Protokollanweisungen ausgehend vom Namen der Protokollierung, der Protokollierungsebene und dem Nachrichtenmuster mit beliebiger Granularität ausgegeben werden sollen. Apache Log4J 2 ist ein Upgrade auf Log4J, mit erheblichen Verbesserungen gegenüber dem vorherigen Log4j 1.x. Log4J 2 bietet viele der Verbesserungen, die in Logback verfügbar sind, während einige inhärente Probleme in der Architektur von Logback behoben werden. Die Apache log4J 2-Senke, auch als Appender bekannt, streamt Ihre Protokolldaten in Ihre Tabelle in Kusto, wo Sie Ihre Protokolle in Echtzeit analysieren und visualisieren können.
Eine vollständige Liste der Datenconnectors finden Sie in der Übersicht über Datenintegrationen.
Voraussetzungen
- Apache Maven
- Azure Data Explorer-Cluster und -Datenbank oder KQL-Datenbank in Microsoft Fabric
Erstellen Ihrer Umgebung
In diesem Abschnitt bereiten Sie Ihre Umgebung auf die Verwendung der Log4J 2-Senke vor.
Installieren des Pakets
Zur Verwendung der Senke in der Anwendung, fügen Sie Ihrer Maven-Datei pom.xml die folgenden Abhängigkeiten hinzu. Die Senke erwartet, dass der Log4j-Kern als Abhängigkeit in der Anwendung bereitgestellt wird.
<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>
Erstellen einer Microsoft Entra-App-Registrierung
Melden Sie sich per Azure CLI an Ihrem Azure-Abonnement an. Führen Sie anschließend im Browser die Authentifizierung durch.
az loginWählen Sie das Abonnement aus, um den Prinzipal zu hosten. Dieser Schritt ist erforderlich, wenn Sie über mehrere Abonnements verfügen.
az account set --subscription YOUR_SUBSCRIPTION_GUIDErstellen Sie den Dienstprinzipal. In diesem Beispiel wird der Dienstprinzipal als
my-service-principalbezeichnet.az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}Kopieren Sie aus den zurückgegebenen JSON-Daten
appId,passwordundtenantfür die zukünftige Verwendung.{ "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" }
Sie haben Ihre Microsoft Entra-Anwendung und den Dienstprinzipal erstellt.
Zuweisen der App-Berechtigung für Microsoft
Führen Sie in Ihrer Abfrageumgebung den folgenden Verwaltungsbefehl aus, und ersetzen Sie dabei den Platzhalter DatabaseName und die Anwendungs-ID durch die zuvor gespeicherten Werte. Dieser Befehl gewährt der App die Rolle Datenbankingestor. Weitere Informationen finden Sie unter Verwalten von Sicherheitsrollen der Datenbank.
.add database DatabaseName ingestors ('aadappID=12345-abcd-12a3-b123-ccdd12345a1b') 'App Registration'Hinweis
Der letzte Parameter ist eine Zeichenfolge, die als Notizen angezeigt wird, wenn Sie die einer Datenbank zugeordneten Rollen abfragen. Weitere Informationen finden Sie unter Verwalten von Datenbankrollen.
Erstellen einer Tabellen- und Ingestionszuordnung
Erstellen Sie eine Zieltabelle für die eingehenden Daten, und ordnen Sie die aufgenommenen Datenspalten den Spalten in der Zieltabelle zu. In den folgenden Schritten entspricht das Tabellenschema und die Zuordnung den Daten, die von der Beispiel-App gesendet werden.
Führen Sie im Abfrage-Editor den folgenden Tabellenerstellungsbefehl aus, und ersetzen Sie den Platzhalter TableName durch den Namen der Zieltabelle:
.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)Führen Sie den folgenden Zuordnungsbefehl Ingestion aus, und ersetzen Sie die Platzhalter TableName durch den Zieltabellennamen und TableNameMapping durch den Namen der Ingestionszuordnung:
.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}]'
Hinzufügen der Log4j 2-Senke zu Ihrer App
Verwenden Sie die folgenden Schritte für Folgendes:
- Hinzufügen der Log4j 2-Senke zu Ihrer App
- Konfigurieren der von der Senke verwendeten Variablen
- Erstellen und Ausführen der App
Fügen Sie Ihrer App den folgenden Code hinzu:
package com.microsoft.azure.kusto.log4j.sample; import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger;Konfigurieren Sie die Log4j 2-Senke, indem Sie den
KustoStrategy-Eintrag zur Datei log4j2.xml hinzufügen und Platzhalter mithilfe der folgenden Informationen in der Tabelle ersetzen:Der Log4J 2-Konnector verwendet eine benutzerdefinierte Strategie, die in RollingFileAppender verwendet wird. Protokolle werden in die rollierende Datei geschrieben, um Datenverluste aufgrund von Netzwerkfehlern beim Herstellen einer Verbindung mit dem Kusto-Cluster zu verhindern. Die Daten werden in einer rollierenden Datei gespeichert und dann in den Kusto-Cluster geleert.
<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" />Eigenschaft Beschreibung clusterIngestUrl Der Ingestion-URI für Ihren Cluster im Format https://ingest-<Cluster>.<region>.kusto.windows.net. dbName Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung. tableName Der Name der vorhandenen Zieltabelle unter Berücksichtigung der Groß-/Kleinschreibung. Beispielsweise ist Log4jTest der Name der Tabelle, die in Erstellen einer Tabellen- und Ingestionszuordnungand ingestion mapping erstellt wurde. appId Die für die Authentifizierung erforderliche Anwendungsclient-ID. Sie speichern diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung. appKey Der für die Authentifizierung erforderliche Anwendungsschlüssel. Sie speichern diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung. appTenant Die ID des Mandanten, in dem die Anwendung registriert ist. Sie speichern diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung. logTableMapping Der Name der Zuordnung. Mappingtype Der Typ der zu verwendenden Zuordnung. Das Standardformat ist csv. flushImmediately Wenn dieser Wert auf true festgelegt ist, löscht die Senke den Puffer nach jedem Protokollereignis. Der Standardwert ist FALSE. Weitere Optionen finden Sie unter Senkenoptionen.
Senden Sie Daten mithilfe der Log4j 2-Senke an Kusto. Zum Beispiel:
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); } }Erstellen Sie die App, und führen Sie sie aus.
Überprüfen Sie, ob sich die Daten in Ihrem Cluster befinden. Führen Sie in Ihrer Abfrageumgebung die folgende Abfrage aus, indem Sie den Platzhalter durch den Namen der Tabelle ersetzen, die zuvor verwendet wurde:
<TableName> | take 10
Ausführen der Beispiel-App
Klonen Sie das Git-Repository log4J 2 mit dem folgenden Git-Befehl:
git clone https://github.com/Azure/azure-kusto-log4j.gitLegen Sie die folgenden Umgebungsvariablen fest, um die Log4J 2-Senke zu konfigurieren:
Hinweis
Im Beispielprojekt, das im Git-Repository enthalten ist, wird das Standardkonfigurationsformat in der Datei log4j2.xml definiert. Diese Konfigurationsdatei befindet sich unter dem Dateipfad: \azure-kusto-log4j\samples\src\main\resources\log4j2.xml.
Navigieren Sie in Ihrem Terminal zum Beispielordner des geklonten Repositorys, und führen Sie den folgenden Maven-Befehl aus:
mvn compile exec:java -Dexec.mainClass="org.example.KustoLog4JSampleApp"Wählen Sie in Ihrer Abfrageumgebung die Zieldatenbank aus, und führen Sie die folgende Abfrage aus, um die aufgenommenen Daten zu untersuchen. Ersetzen Sie dann den Platzhalter TableName durch den Namen der Zieltabelle:
<TableName> | take 10Ihre Ausgabe sollte in etwa wie die folgende Tabelle aussehen:
