Compartilhar via

Ingerir dados com o conector do Apache log4J 2

  • Artigo

O Log4J é uma estrutura de registro em log popular para aplicativos Java mantido pela Apache Foundation. O Log4J permite que os desenvolvedores controlem quais instruções de log são geradas com granularidade arbitrária com base no nome, no nível do registrador e no padrão de mensagem do registrador. O Apache Log4J 2 é uma atualização do Log4J, com melhorias significativas em relação ao Log4j 1.x anterior. O Log4J 2 fornece muitas das melhorias disponíveis no Logback, enquanto corrige alguns problemas inerentes à arquitetura do Logback. O coletor Apache log4J 2, também conhecido como appender, transmite seus dados de log para a sua tabela no Kusto, onde você pode analisar e visualizar logs em tempo real.

Para obter uma lista completa de conectores de dados, consulte Visão geral das integrações de dados.

Pré-requisitos

Configure seu ambiente

Nesta seção, você prepara seu ambiente para usar o coletor Log4J 2.

Instalar o pacote

Para usar o coletor, em um aplicativo, adicione as dependências a seguir ao arquivo pom.xml do Maven. O coletor espera que o log4j-core seja fornecido como uma dependência no aplicativo.

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

Criar um registro de aplicativo do Microsoft Entra

  1. Inicie sessão na sua assinatura do Azure com a CLI do Azure. Em seguida, autentique no navegador.

    az login

  2. Escolha a assinatura para hospedar a entidade de segurança. Essa etapa é necessária quando você tem várias assinaturas.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Crie a entidade de serviço. Neste exemplo, a entidade de serviço é chamada my-service-principal.

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

  4. A partir dos dados JSON retornados, copie o appId, password e tenant para uso futuro.

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

Você criou o aplicativo do Microsoft Entra e a entidade de serviço.

Conceder permissões ao aplicativo do Microsoft Entra

  1. Em seu ambiente de consulta, execute o seguinte comando de gerenciamento, substituindo os espaços reservados DatabaseName e ID do aplicativo pelos valores salvos anteriormente. Esse comando concede ao aplicativo a função de ingestor de banco de dados. Para obter mais informações, consulte Gerenciar unções de segurança de banco de dados.

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

    Observação

    O último parâmetro é uma cadeia de caracteres que aparece como observações quando você consulta as funções associadas a um banco de dados. Para obter mais informações, consulte Gerenciar funções de banco de dados.

Criar uma tabela e mapeamento de ingestão.

Crie uma tabela de destino para os dados de entrada, mapeando as colunas de dados ingeridas para as colunas na tabela de destino. Nas etapas a seguir, o esquema e o mapeamento da tabela correspondem aos dados enviados do aplicativo de exemplo.

  1. No editor de consultas, execute o seguinte comando de criação de tabela, substituindo o espaço reservado TableName pelo nome da tabela 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. Execute o seguinte comando de mapeamento de ingestão, substituindo os espaços reservados TableName pelo nome da tabela de destino e TableNameMapping pelo nome do mapeamento de ingestão:

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

Adicionar o coletor Log4j 2 ao seu aplicativo

Use as seguintes etapas para:

  • Adicionar o coletor Log4j 2 ao seu aplicativo
  • Configurar as variáveis usadas pelo coletor
  • Compilar e executar o aplicativo

  1. Adicione o código a seguir ao seu aplicativo:

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

  2. Configure o coletor Log4j 2 adicionando a entrada KustoStrategy ao arquivo log4j2.xml, substituindo espaços reservados usando as informações na tabela a seguir:

    O conector log4J 2 usa uma estratégia personalizada usada no RollingFileAppender. Os logs são gravados no arquivo de rolagem para evitar qualquer perda de dados decorrente de falha de rede durante a conexão com o cluster Kusto. Os dados são armazenados em um arquivo de rolagem e, em seguida, liberados para o cluster 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"
/>
    Propriedade Descrição
    clusterIngestUrl O URI de ingestão para o cluster no formaro https://ingest-<cluster>.<região>.kusto.windows.net.
    dbName O nome que diferencia maiúsculas de minúsculas do banco de dados de destino.
    tableName O nome que diferencia maiúsculas de minúsculas da tabela de destino existente. Por exemplo, Log4jTest é o nome da tabela criada em Criar uma tabela e mapeamento de ingestão.
    appId O ID do cliente do aplicativo necessário para autenticação. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.
    appKey A chave do aplicativo necessária para autenticação. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.
    appTenant O identificador do locatário em que o aplicativo está registrado. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.
    logTableMapping O nome do mapeamento.
    mappingType O tipo de mapeamento a ser usado. O padrão é csv.
    flushImmediately Se definido como true, o coletor libera o buffer após cada evento de log. O padrão é false.

    Para obter mais opções, consulte Opções de coletor.

  3. Enviar dados para o Kusto usando o coletor Log4j 2. Por exemplo:

    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. Compilar e executar o aplicativo.

  5. Verificar se os dados estão no cluster. Em seu ambiente de consulta, execute a seguinte consulta substituindo o espaço reservado pelo nome da tabela usada anteriormente:

    <TableName>
| take 10

Executar o aplicativo de exemplo

  1. Clone o repositório git log4J 2 usando o seguinte comando git:

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

  2. Defina as seguintes variáveis de ambiente para configurar o coletor Log4J 2:

    Observação

    No projeto de exemplo incluído no repositório git, o formato de configuração padrão é definido no arquivo log4j2.xml. Esse arquivo de configuração está localizado no caminho do arquivo: \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. No terminal, navegue até a pasta de exemplos do repositório clonado e execute o seguinte comando do Maven:

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

  4. Em seu ambiente de consulta, selecione o banco de dados de destino e execute a seguinte consulta para explorar os dados ingeridos, substituindo o espaço reservado TableName pelo nome da tabela de destino:

    <TableName>
| take 10

    A saída deve ser semelhante à seguinte tabela:

    Captura de tela da tabela com a função take 10 e os resultados.

Conteúdo relacionado