Ingerir dados com o NLog sink no Azure Data Explorer

NLog é uma plataforma de log flexível e gratuita para várias plataformas .NET, incluindo o padrão .NET. NLog permite que você escreva em vários destinos, como um banco de dados, arquivo ou console. Com o NLog, você pode alterar a configuração de registro em tempo real. O coletor NLog é um destino para NLog que permite enviar suas mensagens de log para um cluster KQL. O plug-in é criado sobre a biblioteca Azure-Kusto-Data e fornece uma maneira eficiente de coletar seus logs para o cluster.

Neste artigo vais aprender como ingerir dados com o nLog sink.

Para obter uma lista completa de conectores de dados, consulte Visão geral dos conectores de dados.

Pré-requisitos

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

Configurar o ambiente

Nesta seção, você preparará seu ambiente para usar o conector NLog.

Instale o pacote

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

Install-Package NLog.Azure.Kusto

Criar um registo da aplicação Microsoft Entra

A autenticação de aplicativos Microsoft Entra é usada para aplicativos que precisam acessar a plataforma sem a presença de um usuário. Para obter dados usando o conector NLog, você precisa criar e registrar uma entidade de serviço do Microsoft Entra e, em seguida, autorizar essa entidade a obter dados de um banco de dados.

A entidade de serviço do Microsoft Entra pode ser criada através do portal do Azure ou programaticamente, como no exemplo a seguir.

Esta entidade de serviço será a identidade usada pelo conector para gravar dados da sua tabela no Kusto. Mais tarde, você concederá permissões para que essa entidade de serviço acesse os recursos do Kusto.

Inicie sessão na sua subscrição do Azure através da CLI do Azure. Em seguida, autentique-se no navegador.
```
az login
```
Escolha a assinatura para hospedar o principal. Esta etapa é necessária quando você tem várias assinaturas.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Crie a entidade de serviço principal. Neste exemplo, o principal de serviço é chamado my-service-principal.
```
az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}
```

Dos dados JSON retornados, copie o appId, passworde 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 a sua aplicação e principal de serviço do Microsoft Entra.

Salve os seguintes valores para serem usados em etapas posteriores: * ID do aplicativo (cliente) * ID do diretório (locatário) * Valor da chave secreta do cliente

Conceder permissões ao aplicativo Microsoft Entra

Em seu ambiente de consulta, execute o seguinte comando de gerenciamento, substituindo os espaços reservados. Substitua DatabaseName pelo nome do banco de dados de destino e ApplicationID pelo valor salvo anteriormente. Este comando concede ao aplicativo a função de ingestor de banco de dados. Para obter mais informações, consulte Gerenciar funções de segurança de banco de dados.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'NLOG Azure App Registration role'
```
Observação

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

Criar uma tabela e um mapeamento de ingestão

Crie uma tabela de alvos para os dados recebidos.

No seu editor de consultas, execute o seguinte comando de criação de tabela, substituindo o marcador TableName pelo nome da tabela alvo:

.create table <TableName> (Timestamp:datetime, Level:string, Message:string, FormattedMessage:dynamic, Exception:string, Properties:dynamic)

Adicionar a configuração de destino ao seu aplicativo

Use as seguintes etapas para:

Adicionar a configuração de destino
Criar e executar o aplicativo

Adicione o destino em seu arquivo de configuração NLog.

<targets>
    <target name="targettable" xsi:type="TargetTable"
    IngestionEndpointUri="<Connection string>"
    Database="<Database name>"
    TableName="<Table name>"
    ApplicationClientId="<Entra App clientId>"
    ApplicationKey="<Entra App key>"
    Authority="<Entra tenant id>"
    />
</targets>

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

Para obter mais opções, consulte Conector Nlog.

Envie dados usando o coletor 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 você estiver usando o Visual Studio, pressione F5.
Verifique 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 que você usou anteriormente:
```
<TableName>
| take 10
```

Executar o aplicativo de exemplo

Use o aplicativo gerador de log de exemplo como um exemplo mostrando como configurar e usar o coletor NLog.

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

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

Variable	Description
INGEST_ENDPOINT	O URI de ingestão para o seu destino de dados. Você copiou esse URI nos pré-requisitos.
BASE DE DADOS	O nome do banco de dados de destino com distinção entre maiúsculas e minúsculas.
APP_ID	ID do cliente do aplicativo necessário para autenticação. Você salvou esse valor em Criar um registro de aplicativo Microsoft Entra.
APP_KEY	Chave de aplicativo necessária para autenticação. Você salvou esse valor em Criar um registro do aplicativo Microsoft Entra.
AZURE_TENANT_ID	A ID do locatário no qual o aplicativo está registrado. Você salvou esse valor em Criar um registro do aplicativo Microsoft Entra.

Você pode definir as variáveis de ambiente manualmente ou usando 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>"

Dentro do seu terminal, navegue até a pasta raiz do repositório clonado e execute o seguinte dotnet comando para criar o aplicativo:
```
cd .\NLog.Azure.Kusto.Samples\
dotnet build
```
Dentro do seu terminal, navegue até a pasta de exemplos e execute o seguinte dotnet comando para executar o aplicativo:
```
dotnet run
```
No ambiente de consulta, selecione o banco de dados de destino e execute a seguinte consulta para explorar os dados ingeridos.
```
ADXNLogSample
| take 10
```
Sua saída deve ser semelhante à seguinte imagem:

Descrição geral dos conectores de dados
Visão geral do Kusto Query Language (KQL)

Feedback

Esta página foi útil?

Last updated on 2025-11-17