Obter dados com o coletor NLog

2024-11-25

O NLog é uma plataforma de log flexível e gratuita para várias plataformas .NET, incluindo o .NET Standard O NLog permite gravar em vários destinos, como um banco de dados, arquivo ou console. Com o NLog, você pode alterar a configuração de log 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 com base na biblioteca Azure-Kusto-Data e fornece uma maneira eficiente de coletar seus logs no cluster.

Neste artigo, você aprenderá a obter dados com o coletor nLog.

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

Pré-requisitos

SDK do .NET 6.0 ou posterior
Uma assinatura do Azure. Criar uma conta gratuita do Azure.
Um banco de dados KQL no Microsoft Fabric. Copie o URI desse banco de dados usando as instruções em Acessar um banco de dados KQL existente.
Um conjunto de consultas KQL. Isso será chamado de ambiente de consulta.

Configure seu ambiente

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

Instalar o pacote

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

Install-Package NLog.Azure.Kusto

Criar um registro de aplicativo do Microsoft Entra

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

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

Essa entidade de serviço será a identidade utilizada pelo conector para gravar na tabela do Kusto. Posteriormente, você vai conceder permissões para essa entidade de serviço acessar recursos do Kusto.

Inicie sessão na sua assinatura do Azure com a CLI do Azure. Em seguida, autentique no navegador.
```
az login
```
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
```

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}

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.

Salve os seguintes valores a 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 do Microsoft Entra

Em seu ambiente de consulte, execute o comando de gerenciamento a seguir, substituindo os espaços reservados. Substitua DatabaseName pelo nome do banco de dados de destino e ApplicationID pelo valor salvo 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 ('aadapp=<ApplicationID>') 'NLOG Azure App Registration role'
```
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 Exibir funções de segurança existentes.

Criar uma tabela e mapeamento de ingestão.

Crie uma tabela vazia como tabela de destino para os dados de entrada.

Adicionar a configuração de destino ao seu aplicativo

Use as seguintes etapas para:

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

Adicione o destino ao 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.

Enviar 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);

Compilar e executar o aplicativo. Por exemplo, se você estiver usando o Visual Studio, pressione F5.
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 que você usou anteriormente:
```
<TableName>
| take 10
```

Executar o aplicativo de exemplo

Use o aplicativo de 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 de ambiente para que o arquivo de configuração NLog possa lê-las imediatamente a partir do ambiente:

Variável	Descrição
INGEST_ENDPOINT	O URI de ingestão para seu destino de dados. Você copiou esse URI nos pré-requisitos.
DATABASE	O nome que diferencia maiúsculas de minúsculas do banco de dados de destino.
APP_ID	ID do cliente do aplicativo necessária para autenticação. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.
APP_KEY	Chave de aplicativo necessária para autenticação. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.
AZURE_TENANT_ID	O identificador do locatário em que o aplicativo está registrado. Você salvou esse valor em Criar um registro de aplicativo do Microsoft Entra.

Você pode definir as variáveis de ambiente manualmente ou usar 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 até a pasta raiz do repositório clonado e execute o comando dotnet a seguir para compilar o aplicativo:
```
cd .\NLog.Azure.Kusto.Samples\
dotnet build
```
No terminal, navegue até a pasta de exemplos e execute o comando dotnet a seguir para executar o aplicativo:
```
dotnet run
```
Em seu ambiente de consulta, selecione o banco de dados de destino e execute a consulta a seguir para explorar os dados ingeridos.
```
ADXNLogSample
| take 10
```
A saída deve ser semelhante à seguinte imagem:

Visão geral do KQL (Linguagem de Consulta Kusto)