Compartir a través de

Ingesta de datos con el conector Apache log4J 2

  • Artículo

Log4J es un conocido marco de registro para aplicaciones Java mantenido por Apache Foundation. Log4J permite a los desarrolladores controlar qué instrucciones de registro se generan con granularidad arbitraria en función del nombre del registrador, el nivel del registrador y el patrón de mensaje. Apache Log4J 2 es una actualización de Log4J, con mejoras significativas respecto a Log4j 1.x anterior. Log4J 2 proporciona muchas de las mejoras disponibles en Logback, al tiempo que corrige algunos problemas inherentes en la arquitectura de Logback. El receptor Apache log4J 2, también denominado appender, permite transmitir los datos de registro a la tabla en Kusto, donde puede analizar y visualizar los registros en tiempo real.

Para obtener una lista completa de los conectores de datos, consulte Introducción a las integraciones de datos.

Requisitos previos

Configurar el entorno

En esta sección, preparará el entorno para usar el receptor Log4J 2.

Instalar el paquete

Para usar el receptor en una aplicación, agregue las siguientes dependencias a su archivo pom.xml de Maven. El receptor espera que log4j-core se proporcione como una dependencia en la aplicación.

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

Crear un registro de aplicación Microsoft Entra

  1. Inicie sesión en su suscripción de Azure a través de la CLI de Azure. A continuación, realice la autenticación en el explorador.

    az login

  2. Elija la suscripción para hospedar la entidad de servicio. Este paso es necesario si tiene varias suscripciones.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Cree la entidad de servicio. En este ejemplo, la entidad de servicio se llama my-service-principal.

    az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}

  4. En los datos JSON devueltos, copie los valores appId, password y tenant para usarlos posteriormente.

    {
  "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"
}

Ha creado una aplicación de Microsoft Entra y una entidad de servicio.

Conceder permisos a la aplicación Microsoft Entra

  1. En el entorno de consulta, ejecute el siguiente comando de administración y reemplace los marcadores de posición DatabaseName y application ID por los valores guardados anteriormente. Este comando concede a la aplicación el rol de agente de ingesta de bases de datos. Para más información, consulte Administrar roles de seguridad de base de datos.

    .add database DatabaseName ingestors ('aadappID=12345-abcd-12a3-b123-ccdd12345a1b') 'App Registration'

    Nota:

    El último parámetro es una cadena que se muestra como una nota al consultar los roles asociados a una base de datos. Para más información, consulte Administrar roles de base de datos.

Crear una tabla y una asignación de ingesta

Cree una tabla de destino para los datos entrantes asignando las columnas de datos ingeridas a las columnas de la tabla de destino. En los pasos siguientes, la asignación y el esquema de tabla corresponden a los datos enviados desde la app de ejemplo.

  1. En el editor de consultas, ejecute el siguiente comando de creación de tablas y reemplace el marcador de posición TableName por el nombre de la tabla de destino:

    .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. Ejecute el siguiente comando de asignación de ingesta, reemplazando los marcadores de posición TableName por el nombre de la tabla de destino y TableNameMapping por el nombre de la asignación de ingesta:

    .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}]'

Agregar el receptor Log4j 2 a la aplicación

Uso los pasos siguientes para:

  • Agregar el receptor Log4j 2 a la aplicación
  • Configurar las variables usadas por el receptor
  • Compilar y ejecutar la aplicación

  1. Agregue el siguiente código a su app:

    package com.microsoft.azure.kusto.log4j.sample;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

  2. Configure el receptor Log4j 2 agregando la entrada KustoStrategy al archivo log4j2.xml, reemplazando los marcadores de posición mediante la información de la tabla siguiente:

    El conector log4J 2 emplea una estrategia personalizada que se usa en RollingFileAppender. Los registros se escriben en el archivo gradual para evitar cualquier pérdida de datos que surja de un error de red al conectarse al clúster de Kusto. Los datos se almacenan en un archivo gradual y, a continuación, se vacían en el clúster de 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"
/>
    Propiedad Descripción
    clusterIngestUrl Identificador URI de ingesta del clúster en el formato https://ingest-<clúster>.<región>.kusto.windows.net.
    dbName Nombre de la base de datos de destino en el que se distinguen mayúsculas de minúsculas.
    tableName Nombre de una tabla de destino existente en el que se distinguen mayúsculas de minúsculas. Por ejemplo, Log4jTest es el nombre de la tabla creada en Crear una tabla y una asignación de ingesta.
    appId El id. de cliente de la aplicación necesario para la autenticación. Ha guardado este valor en Crear un registro de aplicación Microsoft Entra.
    appKey La clave de aplicación necesaria para la autenticación. Ha guardado este valor en Crear un registro de aplicación Microsoft Entra.
    appTenant El id. del inquilino en el que se registra la aplicación. Ha guardado este valor en Crear un registro de aplicación Microsoft Entra.
    logTableMapping El nombre de la asignación.
    mappingType El tipo de asignación que se va a usar. El valor predeterminado es csv.
    flushImmediately Si se establece en true, el receptor vacía el búfer después de cada evento de registro. El valor predeterminado es false.

    Para ver más opciones, consulte Opciones de receptor.

  3. Envíe datos a Kusto mediante el receptor Log4j 2. Por ejemplo:

    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. Compile y ejecute la aplicación.

  5. Compruebe que los datos estén en el clúster. En el entorno de consulta, ejecute la consulta siguiente reemplazando el marcador de posición por el nombre de la tabla que usó anteriormente:

    <TableName>
| take 10

Ejecutar la aplicación de ejemplo

  1. Clone el repositorio de Git Log4J 2 mediante el siguiente comando de Git:

    git clone https://github.com/Azure/azure-kusto-log4j.git

  2. Defina las siguientes variables de entorno para configurar el receptor Log4J 2:

    Nota:

    En el proyecto de ejemplo incluido en el repositorio de Git, el formato de configuración predeterminado se define en el archivo log4j2.xml. Este archivo de configuración se encuentra en la ruta de acceso del archivo: \azure-kusto-log4j\samples\src\main\resources\log4j2.xml.

    $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. En el terminal, vaya a la carpeta samples del repositorio clonado y ejecute el siguiente comando de Maven:

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

  4. En el entorno de consulta, seleccione la base de datos de destino y ejecute la siguiente consulta para explorar los datos ingeridos, reemplazando el marcador de posición TableName por el nombre de la tabla de destino:

    <TableName>
| take 10

    La salida debe tener una apariencia similar a la tabla siguiente:

    Captura de pantalla de la tabla con la toma de 10 funciones y resultados.

Contenido relacionado