Ingerir dados com o sink do NLog no Azure Data Explorer

2023-11-15

Importante

Este conector pode ser utilizado na Análise em Tempo Real no Microsoft Fabric. Utilize as instruções neste artigo com as seguintes exceções:

Se necessário, crie bases de dados com as instruções em Criar uma base de dados KQL.
Se necessário, crie tabelas com as instruções em Criar uma tabela vazia.
Obtenha URIs de consulta ou ingestão com as instruções em Copiar URI.
Execute consultas num conjunto de consultas KQL.

O NLog é uma plataforma de registo flexível e gratuita para várias plataformas .NET, incluindo o padrão .NET. O NLog permite-lhe escrever em vários destinos, como uma base de dados, um ficheiro ou uma consola. Com o NLog, pode alterar a configuração de registo no local. O sink do NLog é um destino para o NLog que lhe permite enviar as suas mensagens de registo para um cluster do Azure Data Explorer. O plug-in baseia-se na biblioteca Azure-Kusto-Data e fornece uma forma eficiente de afundar os registos no cluster.

Neste artigo, vai aprender a:

Configurar o ambiente
Adicionar a configuração de destino do Azure Data Explorer à sua aplicação
Execute a aplicação de exemplo

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

Pré-requisitos

SDK .NET 6.0 ou posterior
Um cluster e uma base de dados do Azure Data Explorer

Configurar o ambiente

Nesta secção, irá preparar o seu ambiente para utilizar o conector NLog.

Instalar o pacote

Adicione o pacote NuGet NLog.Azure.Kusto . Utilize o comando Install-Package especificando o nome do pacote NuGet.

Install-Package NLog.Azure.Kusto

Criar um registo de aplicações Microsoft Entra

Microsoft Entra autenticação de aplicações é utilizada para aplicações que precisam de aceder ao Azure Data Explorer sem um utilizador presente. Para ingerir dados com o conector NLog, tem de criar e registar um principal de serviço Microsoft Entra e, em seguida, autorizar este principal a ingerir dados numa base de dados do Azure Data Explorer.

Com o cluster do Azure Data Explorer, siga os passos 1 a 7 em Criar um registo de aplicações Microsoft Entra no Azure Data Explorer.
Guarde os seguintes valores para serem utilizados em passos posteriores:
- ID da Aplicação (cliente)
- ID do Diretório (inquilino)
- Valor da chave de segredo do cliente

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

No separador consulta da IU da Web, ligue-se ao cluster. Para obter mais informações sobre como ligar, veja Adicionar clusters.
Navegue para a base de dados na qual pretende ingerir dados.
Execute o seguinte comando de gestão, substituindo os marcadores de posição. Substitua DatabaseName pelo nome da base de dados de destino e ApplicationID pelo valor guardado 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 ('aadapp=<ApplicationID>') 'Azure Data Explorer 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 Ver funções de segurança existentes.

Criar uma tabela e mapeamento de ingestão

Crie uma tabela de destino para os dados recebidos.

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 <TableName> (Timestamp:datetime, Level:string, Message:string, FormattedMessage:dynamic, Exception:string, Properties:dynamic)
```

Adicionar a configuração de destino do Azure Data Explorer à sua aplicação

Utilize os seguintes passos para:

Adicionar a configuração de destino do Azure Data Explorer
Compilar e executar a aplicação

Adicione o destino Data Explorer do Azure no ficheiro de configuração do NLog.

<targets>
    <target name="adxtarget" xsi:type="ADXTarget"
    IngestionEndpointUri="<ADX connection string>"
    Database="<ADX database name>"
    TableName="<ADX table name>"
    ApplicationClientId="<AAD App clientId>"
    ApplicationKey="<AAD App key>"
    Authority="<AAD tenant id>"
    />
</targets>

##Rules
<rules>
    <logger name="*" minlevel="Info" writeTo="adxtarget" />
</rules>

Para obter mais opções, veja Conector Nlog do Azure Data Explorer.

Enviar dados para o Azure Data Explorer com o sink NLog. Por exemplo:

logger.Info("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
logger.Error(exceptionObj, "This was exception");
logger.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
logger.Warn("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);

Compile e execute a aplicação. Por exemplo, se estiver a utilizar o Visual Studio, prima F5.
Verifique se os dados estão no cluster. Na IU da Web, 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

Utilize a aplicação geradora de registos de exemplo como exemplo que mostra como configurar e utilizar o sink do NLog.

Clone o repositório git do sink do NLog com o seguinte comando git:
```
git clone https://github.com/Azure/azure-kusto-nlog-sink.git
```

Defina as seguintes variáveis ambientais, para que o ficheiro de configuração do NLog possa lê-las imediatamente a partir do ambiente:

Variável	Descrição
INGEST_ENDPOINT	O URI de ingestão do cluster no cluster> de formatoshttps://ingest-<.<region.kusto.windows.net>.
BASE DE DADOS	O nome sensível às maiúsculas e minúsculas da base de dados de destino.
APP_ID	ID do cliente da aplicação necessário para autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
APP_KEY	Chave de aplicação necessária para autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
AZURE_TENANT_ID	O ID do inquilino no qual a aplicação está registada. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.

Pode definir manualmente as variáveis de ambiente ou utilizar os seguintes comandos:

Windows
Mac/Linux

$env:INGEST_ENDPOINT="<ingestionURI>"
$env:APP_ID="<appId>"
$env:APP_KEY="<appKey>"
$env:AZURE_TENANT_ID="<tenant>"
$env:DATABASE="<databaseName>"

export INGEST_ENDPOINT="<ingestionURI>"
export APP_ID="<appId>"
export APP_KEY="<appKey>"
export AZURE_TENANT_ID="<tenant>"
export DATABASE="<databaseName>"

No terminal, navegue para a pasta raiz do repositório clonado e execute o seguinte dotnet comando para criar a aplicação:
```
cd .\NLog.Azure.Kusto.Samples\
dotnet build
```
No terminal, navegue para a pasta de exemplos e execute o seguinte dotnet comando para executar a aplicação:
```
dotnet run
```
Na IU da Web, selecione a base de dados de destino e execute a seguinte consulta para explorar os dados ingeridos.
```
ADXNLogSample
| take 10
```
O resultado deve ter um aspeto semelhante à seguinte imagem: