Inserire dati con il sink Serilog in Azure Esplora dati

2025-06-09

Serilog è un framework di registrazione diffuso per le applicazioni .NET. Serilog consente agli sviluppatori di controllare quali istruzioni di log vengono restituite con granularità arbitraria in base al nome, al livello del logger e al modello di messaggio. Il sink Serilog, noto anche come appender, trasmette i dati di log alla tabella, in cui è possibile analizzare e visualizzare i log in tempo reale.

Questo articolo illustra come inserire dati con Serilog.

Per un elenco completo dei connettori dati, vedere Panoramica delle integrazioni dei dati.

Prerequisiti

.NET SDK 6.0 o versione successiva
Un cluster e un database di Azure Esplora dati con i criteri di conservazione e cache predefiniti.
Ambiente di query di Azure Esplora dati
URI del cluster Kusto per il valore TargetURI nel clusterhttps://ingest-< di formato>.<region.kusto.windows.net>. Per altre informazioni, vedere Aggiungere una connessione cluster.

Autenticazione

L'autenticazione Di Microsoft Entra viene usata per le applicazioni che devono accedere alla tabella di database KQL senza che sia presente un utente. Per inserire dati usando il connettore Serilog, è possibile usare uno dei metodi di autenticazione seguenti:

Un'entità-servizio Microsoft Entra è un'identità di sicurezza usata dalle applicazioni per accedere a specifiche risorse di Azure. Questa identità viene usata per autenticare il connettore nel database KQL usando un ID client e una password e può essere usata per le applicazioni in esecuzione all'esterno di Azure.
Un'identità gestita viene usata per autenticare il connettore nel database KQL usando un ID client. Le identità gestite vengono usate per le applicazioni in esecuzione in Azure.

Autenticazione del principale del servizio Microsoft Entra
Autenticazione dell'identità gestita

Creare un'entità servizio Microsoft Entra

Creare un principale del servizio Microsoft Entra e quindi autorizzare questo principale come identità utilizzata dal connettore per importare i dati nel database KQL.

L'entità servizio Microsoft Entra può essere creata tramite il Portale di Azure o a livello di programmazione, come nell'esempio seguente.

Successivamente si concedono le autorizzazioni a questa entità servizio per accedere alle risorse Kusto.

Accedere alla sottoscrizione di Azure usando l'interfaccia della riga di comando di Azure. Eseguire quindi l'autenticazione nel browser.
```
az login
```
Scegliere la sottoscrizione per ospitare l'entità di sicurezza. Questo passaggio è necessario quando si hanno più sottoscrizioni.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```

Creare l'entità servizio. In questo esempio l'entità servizio viene chiamata my-service-principal.

az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}

Dai dati JSON restituiti copiare appId, password e tenant per un 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"
}

L'applicazione Microsoft Entra e l'entità servizio sono state create.

Creare un'identità gestita

Creare un'identità gestita e autorizzarla come identità usata dal connettore per inserire i dati nel database KQL. Per altre informazioni sulla creazione di un'identità gestita, vedere Gestire le identità gestite assegnate dall'utente.

Accedere alla sottoscrizione di Azure usando l'interfaccia della riga di comando di Azure. Eseguire quindi l'autenticazione nel browser.
```
az login
```
Scegliere la sottoscrizione per ospitare l'identità gestita. Questo passaggio è necessario quando si hanno più sottoscrizioni.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Creare un'identità gestita assegnata dall'utente. In questo esempio l'identità gestita è denominata my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Assegnare il ruolo Collaboratore per l'ambito della sottoscrizione all'identità gestita. In questo esempio l'identità gestita è denominata my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

Dai dati JSON restituiti copiare il clientId per usi futuri. Il formato JSON è il seguente:

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

Hai creato la tua identità gestita assegnata dall'utente.

Creare una tabella di destinazione e un mapping di inserimento

Creare una tabella di destinazione per i dati in ingresso, e un mapping di inserimento per mappare le colonne di dati inseriti alle colonne della tabella di destinazione. Nei seguenti passaggi lo schema e il mapping della tabella corrispondono ai dati inviati dall'app di esempio.

Nell'editor di query eseguire il comando di creazione della tabella seguente, sostituendo il segnaposto NomeTabella con il nome della tabella di destinazione:

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

Eseguire il comando crea mapping di inserimento seguente, sostituendo i segnaposto NomeTabella con il nome della tabella di destinazione e NomeMappingTabella con il nome del mapping di inserimento:

.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}]'

Usare l'entità servizio da Creare un'entità servizio Microsoft Entra database ingestor per concedere l'autorizzazione per lavorare con il database. Per maggiori informazioni, vedere gli Esempi. Sostituire il segnaposto DatabaseName con il nome del database di destinazione e ApplicationID con il AppId valore salvato durante la creazione di un'entità servizio Microsoft Entra.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Usare Serilog nell’applicazione ASP.NET Core

Questa sezione illustra come integrare Serilog nell'applicazione ASP.NET Core per registrare i dati e inviarli alla tabella KQL.

Installare il pacchetto

Aggiungere il pacchetto di libreria NuGet Serilog.Sinks.AzureDataExplorer. Usare il comando del pacchetto di installazione che specifica il nome del pacchetto NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Aggiungere il sink Serilog all'app

Eseguire la procedura descritta di seguito per:

Aggiungere il sink Serilog all'app.
Configurare le variabili usate dal sink.
Compilare ed eseguire l'app.

Aggiungere il seguente codice all'applicazione:
```
using Serilog.Sinks.AzureDataExplorer;
```

Configurare il sink Serilog sostituendo i segnaposto usando le informazioni nella tabella seguente:

Autenticazione del principale del servizio Microsoft Entra
Autenticazione dell'identità gestita

Per l'autenticazione del principale del servizio di Microsoft Entra, usa il codice seguente:

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

Per l'autenticazione dell'identità gestita usare il codice seguente:

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

Usare la tabella seguente per impostare i valori per le opzioni sink:

Variabile	Descrizione
`IngestionEndPointUri`	URI di inserimento.
`DatabaseName`	Il nome che è sensibile alle maiuscole del database di destinazione.
`TableName`	Nome sensibile alle maiuscole della tabella di destinazione esistente. Ad esempio, SerilogTest è il nome della tabella creata in Creare una tabella di destinazione e il mapping di inserimento.
`AppId`	ID client dell'applicazione necessario per l'autenticazione del principal del servizio di Microsoft Entra. Questo valore è stato salvato in Creare un'entità servizio Microsoft Entra.
`AppKey`	Chiave dell'applicazione necessaria per l'autenticazione dell'entità servizio Microsoft Entra. Questo valore è stato salvato come `password` in Creare un'entità servizio Microsoft Entra.
`Tenant`	L'ID del tenant in cui l'applicazione viene registrata quando si utilizza l'autenticazione con l'entità del servizio Microsoft Entra. Questo valore è stato salvato in Creare un'entità servizio Microsoft Entra.
`BufferBaseFileName`	Nome file di base facoltativo per il file di buffer. Impostare questo valore se è necessario che i log siano durevoli in caso di perdita di errori di connessione risultanti nel cluster. Ad esempio: `C:/Temp/Serilog`.
`ManagedIdentityClientId`	ID client dell'identità gestita assegnata dall'utente, quando si usa l'autenticazione dell'identità gestita.

Per altre opzioni, vedere Opzioni sink.

Inviare dati al database usando il sink Serilog. Ad esempio:

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

Compilare ed eseguire l'app. Ad esempio, se si usa Visual Studio, premere F5.
Verificare che i dati si trovino nella tabella. Eseguire la query seguente sostituendo il segnaposto con il nome della tabella creata in un passaggio precedente:
```
<TableName>
| take 10
```

Eseguire l'app di esempio

Se non si hanno dati personalizzati da testare, è possibile usare l'app generatore di log di esempio con dati di esempio per testare la configurazione e l'uso del sink Serilog.

Clonare il sink Serilog repository git usando il comando git seguente:

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

Impostare le variabili di ambiente seguenti per configurare il sink Serilog:

Variabile	Descrizione
`IngestionEndPointUri`	URI di inserimento.
`DatabaseName`	Il nome che è sensibile alle maiuscole del database di destinazione.
`TableName`	Nome sensibile alle maiuscole della tabella di destinazione esistente. Ad esempio, SerilogTest è il nome della tabella creata in Creare una tabella di destinazione e il mapping di inserimento.
`AppId`	ID client dell'applicazione necessario per l'autenticazione del principale del servizio Microsoft Entra. Questo valore è stato salvato in Creare un'entità servizio Microsoft Entra.
`AppKey`	Chiave applicativa necessaria per l'autenticazione del principale servizio Microsoft Entra. Questo valore è stato salvato in Creare un'entità servizio Microsoft Entra.
`Tenant`	L'ID del tenant in cui l'applicazione viene registrata quando si utilizza l'autenticazione con l'entità del servizio Microsoft Entra. Questo valore è stato salvato in Creare un'entità servizio Microsoft Entra.
`BufferBaseFileName`	Nome del file di base per il file di buffer. Impostare questo valore se è necessario che i log siano durevoli in caso di perdita di errori di connessione risultanti nel cluster. Ad esempio, `C:/Temp/Serilog`
`ManagedIdentityClientId`	ID client dell'identità gestita assegnata dall'utente, quando si usa l'autenticazione dell'identità gestita.

Si possono configurare tali variabili di ambiente manualmente o usando i comandi seguenti:

Finestre
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>"

Sul computer esplora la cartella radice del repository clonato ed eseguire il comando .NET seguente per creare l'app:
```
dotnet build src
```
Sul computer esplora la cartella con gli esempi ed eseguire il comando .NET seguente per creare l'app:
```
dotnet build run
```

Nell'ambiente di query selezionare il database di destinazione ed eseguire la query seguente per esplorare i dati inseriti, sostituendo il segnaposto TableName con il nome della tabella di destinazione:
```
<TableName>
| take 10
```
L'output dovrebbe essere simile alla seguente immagine: