Partilhar via

Ingerir dados com o sink serilog no Azure Data Explorer

  • Artigo

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:

O Serilog é uma arquitetura de registo popular para aplicações .NET. O Serilog permite que os programadores controlem que instruções de registo são saída com granularidade arbitrária com base no nome, nível de logger e padrão de mensagem do logger. O sink serilog, também conhecido como appender, para o Azure Data Explorer transmite os seus dados de registo para o Azure Data Explorer, onde pode analisar e visualizar os seus registos em tempo real.

Neste artigo, vai aprender a:

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

Pré-requisitos

Configurar o ambiente

Nesta secção, irá preparar o seu ambiente para utilizar o sink serilog.

Instalar o pacote

Adicione o pacote Serilog.Sinks.AzureDataExplorer NuGet. Utilize o comando Install-Package especificando o nome do pacote NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

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 Serilog, 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.

  1. 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.
  2. 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

  1. No separador consulta da IU da Web, ligue-se ao cluster. Para obter mais informações sobre como ligar, veja Adicionar clusters.

  2. Navegue para a base de dados na qual pretende ingerir dados.

  3. 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, mapeando as colunas de dados ingeridos para as colunas na tabela de destino. Nos passos seguintes, o esquema e o mapeamento da tabela correspondem aos dados enviados a partir da aplicação de exemplo.

  1. 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, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)

  2. Execute o seguinte comando de mapeamento de ingestão, substituindo os marcadores de posição 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}]'

Adicionar o sink do Serilog à sua aplicação

Utilize os seguintes passos para:

  • Adicionar o sink do Serilog à sua aplicação
  • Configurar as variáveis utilizadas pelo sink
  • Compilar e executar a aplicação

  1. Adicione o seguinte código à sua aplicação:

    using Serilog.Sinks.AzureDataExplorer;

  2. Configure o sink serilog, substituindo os marcadores de posição com as informações na tabela que se segue:

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<cluster>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Variável Descrição
    IngestionEndPointUri O URI de ingestão do cluster no cluster> de formatoshttps://ingest-<.<region.kusto.windows.net>.
    DatabaseName O nome sensível às maiúsculas e minúsculas da base de dados de destino.
    TableName O nome sensível às maiúsculas e minúsculas de uma tabela de destino existente. Por exemplo, SerilogTest é o nome da tabela criada em Criar uma tabela e mapeamento de ingestão.
    AppId O ID de cliente da aplicação necessário para autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    AppKey A chave de aplicação necessária para a autenticação. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    Inquilino O ID do inquilino no qual a aplicação está registada. Guardou este valor em Criar um registo da Aplicação Microsoft Entra.
    BufferBaseFileName Nome de ficheiro base opcional para o ficheiro de memória intermédia. Defina este valor se exigir que os registos sejam duráveis face à perda, o que resulta em falhas de ligação ao cluster. Por exemplo, C:/Temp/Serilog.

    Para obter mais opções, veja Opções de Sink.

  3. Enviar dados para o Azure Data Explorer com o sink 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. Compile e execute a aplicação. Por exemplo, se estiver a utilizar o Visual Studio, prima F5.

  5. 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 serilog.

  1. Clone o repositório git do sink serilog com o seguinte comando git:

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

  2. Defina as seguintes variáveis ambientais para configurar o sink serilog:

    Variável Descrição
    IngestionEndPointUri O URI de ingestão do cluster no cluster> de formatoshttps://ingest-<.<region.kusto.windows.net>.
    DatabaseName O nome sensível às maiúsculas e minúsculas da base de dados de destino.
    TableName O nome sensível às maiúsculas e minúsculas de uma tabela de destino existente. Por exemplo, SerilogTest é o nome da tabela criada em Criar uma tabela e mapeamento de ingestão.
    AppId ID de cliente da aplicação necessário para autenticação. Guardou este valor em Criar uma Microsoft Entra Registo de aplicações.
    AppKey Chave da aplicação necessária para a autenticação. Guardou este valor em Criar uma Microsoft Entra Registo de aplicações.
    Inquilino O ID do inquilino no qual a aplicação está registada. Guardou este valor em Criar uma Microsoft Entra Registo de aplicações.
    BufferBaseFileName O nome de ficheiro base do ficheiro de memória intermédia. Defina este valor se exigir que os registos sejam duráveis face a perdas resultantes de falhas de ligação ao cluster. Por exemplo, C:/Temp/Serilog

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

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

  3. No terminal, navegue para a pasta raiz do repositório clonado e execute o seguinte comando .NET para criar a aplicação:

    dotnet build src

  4. No terminal, navegue para a pasta samples e execute o seguinte comando .NET para executar a aplicação:

    dotnet build run

  5. Na IU da Web, selecione a base de dados de destino e execute a seguinte consulta para explorar os dados ingeridos, substituindo o marcador de posição TableName pelo nome da tabela de destino:

    <TableName>
| take 10

    O resultado deverá ter um aspeto semelhante à seguinte imagem:

    Captura de ecrã da tabela com 10 funções e resultados.

Conteúdo relacionado