Ingerir dados com o coletor Serilog no Azure Data Explorer

O Serilog é uma estrutura de log popular para aplicativos .NET. O Serilog 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 coletor Serilog, também conhecido como um appender, transmite seus dados de log para sua tabela, onde você pode analisar e visualizar seus logs em tempo real.

Este artigo mostra como ingerir dados com o Serilog.

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

Pré-requisitos

• SDK do .NET 6.0 ou posterior
• Um cluster e um banco de dados do Azure Data Explorer com as políticas de cache e retenção padrão.
• Ambiente de consulta do Azure Data Explorer
• O URI do cluster Kusto para o valor TargetURI no formato https://ingest-<cluster>.<região>.kusto.windows.net. Para obter mais informações, consulte Adicionar uma conexão de cluster.

Crie uma entidade de serviço do Microsoft Entra.

A autenticação de aplicativo do Microsoft Entra é usada para aplicativos que precisam acessar sua tabela de banco de dados KQL sem que um usuário esteja presente. Para ingerir dados usando o conector Serilog, você precisa criar e registrar uma entidade de serviço do Microsoft Entra e autorizar essa entidade como a identidade usada pelo conector para ingerir dados no banco de dados KQL.

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

Posteriormente, você vai conceder permissões para essa entidade de serviço acessar recursos do Kusto.

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

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

Criar uma tabela de destino e um mapeamento de ingestão

Crie uma tabela de destino para os dados de entrada e um mapeamento de ingestão para mapear 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. Execute o seguinte comando de criação de tabela no editor de consultas, substituindo o espaço reservado TableName pelo nome da tabela de destino:

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

2. Execute o seguinte comando de mapeamento de ingestão .create, substituindo os espaços reservados TableName pelo nome da tabela de destino e TableNameMapping pelo nome do mapeamento de ingestão:

   .create table <TableName> ingestion csv mapping '<TableNameMapping>' '[{"Name":"Timestamp","DataType":"","Ordinal":"0","ConstValue":null},{"Name":"Level","DataType":"","Ordinal":"1","ConstValue":null},{"Name":"Message","DataType":"","Ordinal":"2","ConstValue":null},{"Name":"Exception","DataType":"","Ordinal":"3","ConstValue":null},{"Name":"Properties","DataType":"","Ordinal":"4","ConstValue":null},{"Name":"Position","DataType":"","Ordinal":"5","ConstValue":null},{"Name":"Elapsed","DataType":"","Ordinal":"6","ConstValue":null}]'
   

3. Conceda à entidade de serviço de Criar uma entidade de serviço do Microsoft Entra permissões de função de ingestor de banco de dados para trabalhar com o banco de dados. Para obter mais informações, consulte os Exemplos. Substitua o espaço reservado DatabaseName pelo nome do banco de dados de destino e ApplicationID pelo valor AppId que você salvou ao criar uma entidade de serviço do Microsoft Entra.

   .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
   

Usar o Serilog em seu aplicativo ASP.NET Core

Esta seção explica como integrar o Serilog ao aplicativo ASP.NET Core para registrar dados em log e enviá-los para sua tabela KQL.

Instalar o pacote

Adicione o pacote de biblioteca NuGet Serilog.Sinks.AzureDataExplorer. Use o comando Install-Package que especifica o nome do pacote NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Adicionar o coletor Serilog ao seu aplicativo

Use as seguintes etapas para:

• Adicione o coletor Serilog ao seu aplicativo.
• Configure as variáveis usadas pelo coletor.
• Compilar e executar o aplicativo.

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

   using Serilog.Sinks.AzureDataExplorer;
   

2. Configure o coletor Serilog, substituindo os espaços reservados usando as informações na tabela a seguir:

   var log = new LoggerConfiguration()
   .WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
   {
       IngestionEndpointUri = "<TargetURI>",
       DatabaseName = "<MyDatabase>",
       TableName = "<MyTable>",
       BufferBaseFileName = "<BufferBaseFileName>"
   })
   .CreateLogger();
   

   Variável	Descrição
   IngestionEndPointUri	O URI de ingestão.
   DatabaseName	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, SerilogTest é o nome da tabela criada em Criar uma tabela de destino e mapeamento de ingestão.
   AppId	O ID do cliente do aplicativo necessário para autenticação. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
   AppKey	A chave do aplicativo necessária para autenticação. Você salvou esse valor como password em Criar uma entidade de serviço do Microsoft Entra.
   Locatário	O identificador do locatário em que o aplicativo está registrado. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
   BufferBaseFileName	Nome de arquivo base opcional para o arquivo de buffer. Defina esse valor se você precisar que seus logs sejam duráveis contra perda resultante de falhas de conexão com seu cluster. Por exemplo, C:/Temp/Serilog.

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

3. Envie dados para seu banco de dados usando o coletor Serilog. Por exemplo:

   log.Verbose("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Warning("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Error(new Exception(), "Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
   log.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
   

4. Compilar e executar o aplicativo. Por exemplo, se você estiver usando o Visual Studio, pressione F5.

5. Verifique se os dados estão em sua tabela. Execute a seguinte consulta substituindo o espaço reservado pelo nome da tabela que foi criada em uma etapa anterior:

   <TableName>
   | take 10
   

Executar o aplicativo de exemplo

Se você não tiver seus próprios dados para testar, poderá usar o aplicativo gerador de log de exemplo com dados de exemplo para testar a configuração e o uso do coletor Serilog.

1. Clone o repositório git do coletor Serilog usando o seguinte comando git:

   git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
   

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

   Variável	Descrição
   IngestionEndPointUri	O URI de ingestão.
   DatabaseName	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, SerilogTest é o nome da tabela criada em Criar uma tabela de destino e mapeamento de ingestão.
   AppId	ID do cliente do aplicativo necessária para autenticação. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
   AppKey	Chave de aplicativo necessária para autenticação. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
   Locatário	O identificador do locatário em que o aplicativo está registrado. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
   BufferBaseFileName	O nome do arquivo base para o arquivo de buffer. Defina esse valor se você precisar que seus logs sejam duráveis contra perda resultante de falhas de conexão com seu cluster. Por exemplo, C:/Temp/Serilog

   Você pode definir as variáveis de ambiente manualmente ou usar os seguintes comandos:

   • Windows
   • Mac/Linux

   $env:ingestionURI="<ingestionURI>"
   $env:appId="<appId>"
   $env:appKey="<appKey>"
   $env:tenant="<tenant>"
   $env:databaseName="<databaseName>"
   $env:tableName="<tableName>"
   

3. No terminal, navegue até a pasta raiz do repositório clonado e execute o seguinte comando .NET para criar o aplicativo:

   dotnet build src
   

4. No terminal, navegue até a pasta de exemplos e execute o seguinte comando .NET para executar o aplicativo:

   dotnet build run
   

3. No 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 imagem:

   

Conteúdo relacionado

• Visão geral das integrações de dados
• Visão geral do KQL (Linguagem de Consulta Kusto)