Ingerir dados com o coletor Serilog no Azure Data Explorer

O Serilog é um framework de registo popular para aplicações .NET. O Serilog permite aos programadores controlar que instruções de registo são fornecidas com granularidade arbitrária com base no nome do logger, nível do logger e padrão de mensagem. O coletor Serilog, também conhecido como apêndice, 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 Serilog.

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

Pré-requisitos

.NET SDK 6.0 ou posterior
Um cluster e 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 seu URI de 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.

Autenticação

A autenticação do Microsoft Entra é usada para aplicativos que precisam acessar sua tabela de banco de dados KQL sem a presença de um usuário. Para ingerir dados usando o conector Serilog, você pode usar um dos seguintes métodos de autenticação:

Uma entidade de serviço Microsoft Entra é uma identidade de segurança utilizada por aplicações para aceder a recursos específicos do Azure. Essa identidade é usada para autenticar o conector em seu banco de dados KQL usando uma ID de cliente e senha, e pode ser usada para aplicativos que estão sendo executados fora do Azure.
Uma identidade gerenciada é usada para autenticar o conector no banco de dados KQL usando um ID de cliente. As identidades gerenciadas são usadas para aplicativos que estão sendo executados no Azure.

Autenticação do principal de serviço do Microsoft Entra
Autenticação de Identidade Gerida

Criar um principal de serviço Microsoft Entra

Crie uma entidade de serviço Microsoft Entra e autorize essa entidade como a identidade usada pelo conector para ingerir dados para seu banco de dados KQL.

O principal de serviço do Microsoft Entra pode ser criado programaticamente ou por meio do portal do Azure, como ilustrado no exemplo abaixo.

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 os 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.

Criar uma identidade gerenciada

Crie uma identidade gerenciada e autorize-a como a identidade usada pelo conector para ingerir dados para seu banco de dados KQL. Para obter mais informações sobre como criar uma identidade gerenciada, consulte Gerenciar identidades gerenciadas atribuídas pelo usuário.

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 a identidade gerenciada. Esta etapa é necessária quando você tem várias assinaturas.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Crie uma identidade gerida atribuída pelo utilizador. Neste exemplo, a identidade gerida é chamada my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Atribua a função de Colaborador do escopo da subscrição à identidade gerenciada. Neste exemplo, a identidade gerida é chamada my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

Dos dados JSON retornados, copie o clientId para uso futuro. O JSON tem o seguinte formato:

{
  "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "id": "/subscriptions/00001111-aaaa-2222-bbbb-3333cccc4444/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-managed-identity",
  "location": "eastus",
  "name": "my-managed-identity",
  "principalId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "resourceGroup": "my-resource-group",
  "tags": {},
  "tenantId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Você criou sua identidade gerenciada atribuída pelo usuário.

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

Crie uma tabela de destino para os dados recebidos e um mapeamento de ingestão para alinhar as colunas dos dados ingeridos com 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.

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)

Execute o seguinte comando .create ingestion mapping, 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}]'

Conceda à entidade de serviço de Criar uma entidade de serviço do Microsoft Entra ingestor de banco de dados permissões de função para trabalhar com o banco de dados. Para obter mais informações, consulte Exemplos. Substitua o espaço reservado DatabaseName pelo nome do banco de dados de destino e ApplicationID pelo valor AppId que guardou ao criar um principal de serviço do Microsoft Entra.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Use o Serilog em seu aplicativo ASP.NET Core

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

Instale o pacote

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

Install-Package Serilog.Sinks.AzureDataExplorer

Adicione 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.
Compile e execute a aplicação.

Adicione o seguinte código ao seu aplicativo:
```
using Serilog.Sinks.AzureDataExplorer;
```

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

Autenticação do principal de serviço do Microsoft Entra
Autenticação de Identidade Gerida

Para autenticação do principal do serviço do Microsoft Entra, use o seguinte código:

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

Para autenticação de identidade gerenciada, use o seguinte código:

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

Use a tabela abaixo para definir os valores para as opções de coletor:

Variável	Descrição
`IngestionEndPointUri`	A URI de ingestão.
`DatabaseName`	O nome do banco de dados de destino com distinção entre maiúsculas e minúsculas.
`TableName`	Nome sensível a maiúsculas e minúsculas de uma tabela de destino existente. Por exemplo, SerilogTest é o nome da tabela criada em Criar uma tabela de destino e mapeamento de ingestão.
`AppId`	A ID do cliente do aplicativo necessária para a autenticação da entidade de serviço do Microsoft Entra. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
`AppKey`	A chave de aplicação necessária para a autenticação do principal de serviço do Microsoft Entra. Você salvou esse valor como `password` em Criar uma entidade de serviço do Microsoft Entra.
`Tenant`	O ID do inquilino no qual a aplicação está registada ao usar a autenticação do principal de serviço do Microsoft Entra. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
`BufferBaseFileName`	Nome do arquivo base opcional para o arquivo buffer. Defina esse valor se você exigir que seus logs sejam duráveis contra perdas resultantes de falhas de conexão com o cluster. Por exemplo, `C:/Temp/Serilog`.
`ManagedIdentityClientId`	O ID de cliente da identidade gerida atribuída ao utilizador, quando se utiliza a autenticação de Identidade Gerida.

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

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

Compile e execute a aplicação. Por exemplo, se você estiver usando o Visual Studio, pressione F5.
Verifique se os dados estão na 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 não tiveres os teus próprios dados para testar, podes usar a aplicação geradora de logs de exemplo com dados de exemplo para testar a configuração e o uso do sink Serilog.

Clone o repositório git do coletor Serilog usando o seguinte comando git:
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

Defina as seguintes variáveis ambientais para configurar o coletor Serilog:

Variável	Descrição
`IngestionEndPointUri`	A URI de ingestão.
`DatabaseName`	O nome do banco de dados de destino com distinção entre maiúsculas e minúsculas.
`TableName`	Nome sensível a maiúsculas e minúsculas de uma 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 de cliente da aplicação necessária para a autenticação do principal do Microsoft Entra. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
`AppKey`	Chave de aplicação necessária para a autenticação do principal de serviço do Microsoft Entra. Você salvou esse valor em Criar uma entidade de serviço do Microsoft Entra.
`Tenant`	O ID do inquilino no qual a aplicação está registada ao usar a autenticação do principal de serviço do Microsoft Entra. 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ê exigir que seus logs sejam duráveis contra perdas resultantes de falhas de conexão com o cluster. Por exemplo, `C:/Temp/Serilog`
`ManagedIdentityClientId`	O ID de cliente da identidade gerida atribuída ao utilizador, quando se utiliza a autenticação de Identidade Gerida.

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

Mac OS
Mac/Linux

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

export ingestionURI="<ingestionURI>"
export appId="<appId>"
export appKey="<appKey>"
export tenant="<tenant>"
export databaseName="<databaseName>"
export tableName="<tableName>"
export managedIdentityClientId="<managedIdentityClientId>"

No terminal, navegue até a pasta raiz do repositório clonado e execute o seguinte comando .NET para criar o aplicativo:
```
dotnet build src
```
No terminal, navegue até a pasta de exemplos e execute o seguinte comando .NET para executar o aplicativo:
```
dotnet build run
```

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
```
Sua saída deve ser semelhante à seguinte imagem:

Feedback

Esta página foi útil?

Last updated on 2025-06-09