Partilhar via

Ingerir dados com o conector Apache log4J 2

  • Artigo

O Log4J é uma arquitetura de registo popular para aplicações Java mantida pela Fundação Apache. O Log4J permite que os programadores controlem as instruções de registo que são saídas com granularidade arbitrária com base no nome, nível de logger e padrão de mensagem do logger. O Apache Log4J 2 é uma atualização para Log4J, com melhorias significativas sobre o Log4j 1.x anterior. O Log4J 2 fornece muitas das melhorias disponíveis no Logback, ao mesmo tempo que corrige alguns problemas inerentes na arquitetura do Logback. O sink do Apache log4J 2, também conhecido como appender, transmite os seus dados de registo para a sua tabela no Kusto, onde pode analisar e visualizar os seus registos em tempo real.

Para obter uma lista completa dos conectores de dados, veja Descrição geral das integrações de dados.

Pré-requisitos

Configurar o ambiente

Nesta secção, vai preparar o ambiente para utilizar o sink Log4J 2.

Instalar o pacote

Para utilizar o sink numa aplicação, adicione as seguintes dependências ao ficheiro pom.xml Maven. O sink espera que o log4j-core seja fornecido como uma dependência na aplicação.

<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 registo da Aplicação Microsoft Entra

  1. Inicie sessão na sua subscrição do Azure através da CLI do Azure. Em seguida, autentique-se no browser.

    az login

  2. Escolha a subscrição para alojar o principal. Este passo é necessário quando tem várias subscrições.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Crie o principal de serviço. Neste exemplo, o principal de serviço chama-se my-service-principal.

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

  4. A partir dos dados JSON devolvidos, copie o appId, passworde tenant para utilização futura.

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

Criou a sua aplicação Microsoft Entra e principal de serviço.

Conceder as permissões da aplicação Microsoft Entra

  1. No seu ambiente de consulta, execute o seguinte comando de gestão, substituindo os marcadores de posição DatabaseName e o ID da aplicação pelos valores guardados anteriormente. Este comando concede à aplicação a função de ingestor de bases de dados . Para obter mais informações, veja Gerir funções de segurança de bases de dados.

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

    Nota

    O último parâmetro é uma cadeia que aparece como notas quando consulta as funções associadas a uma base de dados. Para obter mais informações, veja Gerir funções de base de dados.

Criar uma tabela e mapeamento de ingestão

Crie uma tabela de destino para os dados recebidos, mapeando as colunas de dados ingeridos para as colunas na tabela de destino. Nos passos seguintes, o esquema e o mapeamento da tabela correspondem aos dados enviados a partir da aplicação de exemplo.

  1. No editor de consultas, execute o seguinte comando de criação de tabelas, substituindo o marcador de posição 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 marcadores de posição 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 sink log4j 2 à sua aplicação

Utilize os seguintes passos para:

  • Adicionar o sink log4j 2 à sua aplicação
  • Configurar as variáveis utilizadas pelo sink
  • Compilar e executar a aplicação

  1. Adicione o seguinte código à sua aplicação:

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

  2. Configure o sink log4j 2 ao adicionar a KustoStrategy entrada ao ficheiro log4j2.xml, substituindo os marcadores de posição com as informações na tabela que se segue:

    O conector log4J 2 utiliza uma estratégia personalizada utilizada no RollingFileAppender. Os registos são escritos no ficheiro sem interrupção para evitar qualquer perda de dados decorrente de uma falha de rede ao ligar ao cluster do Kusto. Os dados são armazenados num ficheiro sem interrupção e, em seguida, enviados 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 do cluster no cluster> de formatoshttps://ingest-<.<region.kusto.windows.net>.
    dbName O nome sensível às maiúsculas e minúsculas da base de dados de destino.
    tableName O nome sensível às maiúsculas e minúsculas de uma tabela de destino existente. Por exemplo, Log4jTest é o nome da tabela criada em Criar uma tabela e mapeamento de ingestão.
    appId O ID de cliente da aplicação necessário para autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    appKey A chave de aplicação necessária para a autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    appTenant O ID do inquilino no qual a aplicação está registada. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    logTableMapping O nome do mapeamento.
    mappingType O tipo de mapeamento a utilizar. A predefinição é csv.
    flushImmediately Se estiver definido como verdadeiro, o sink limpa a memória intermédia após cada evento de registo. A predefinição é falsa.

    Para obter mais opções, veja Opções de Sink.

  3. Envie dados para o Kusto com o sink 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. Compile e execute a aplicação.

  5. Verifique se os dados estão no cluster. No seu ambiente de consulta, execute a seguinte consulta substituindo o marcador de posição pelo nome da tabela que utilizou anteriormente:

    <TableName>
| take 10

Execute a aplicação de exemplo

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

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

  2. Defina as seguintes variáveis ambientais para configurar o sink Log4J 2:

    Nota

    No projeto de exemplo incluído no repositório git, o formato de configuração predefinido é definido no ficheiro log4j2.xml. Este ficheiro de configuração está localizado no caminho do ficheiro: \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 para a pasta de exemplos do repositório clonado e execute o seguinte comando maven:

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

  4. No ambiente de consulta, selecione a base de dados de destino e execute a seguinte consulta para explorar os dados ingeridos, substituindo o marcador de posição TableName pelo nome da tabela de destino:

    <TableName>
| take 10

    O resultado deve ter um aspeto semelhante à seguinte tabela:

    Captura de ecrã da tabela com 10 funções e resultados.

Conteúdo relacionado