Ingérer des données avec le récepteur Serilog dans Azure Data Explorer

Serilog est un framework de journalisation populaire pour les applications .NET. Serilog permet aux développeurs de contrôler les instructions de journal qui sont sorties avec une granularité arbitraire en fonction du nom, du niveau d’enregistreur d’événements et du modèle de message du journal. Le récepteur Serilog, également appelé appender, diffuse vos données de journal dans votre table, où vous pouvez analyser et visualiser vos journaux en temps réel.

Cet article explique comment ingérer des données avec Serilog.

Pour obtenir une liste complète des connecteurs de données, consultez Vue d’ensemble des intégrations de données.

Prérequis

SDK .NET 6.0 ou ultérieur
Un cluster et une base de données Azure Data Explorer avec les stratégies de cache et de rétention par défaut.
Environnement de requête Azure Data Explorer
Votre URI de cluster Kusto pour la valeur TargetURI au format https://ingest-<cluster>.<région>.kusto.windows.net. Pour plus d’informations, consultez Ajouter une connexion de cluster.

Authentification

L’authentification Microsoft Entra est utilisée pour les applications qui doivent accéder à votre table de base de données KQL sans qu’un utilisateur soit présent. Pour ingérer des données à l’aide du connecteur Serilog, vous pouvez utiliser l’une des méthodes d’authentification suivantes :

Un principal de service Microsoft Entra est une identité de sécurité utilisée par les applications pour accéder à des ressources Azure spécifiques. Cette identité est utilisée pour authentifier le connecteur auprès de votre base de données KQL à l’aide d’un ID client et d’un mot de passe, et peut être utilisée pour les applications qui s’exécutent en dehors d’Azure.
Une identité managée est utilisée pour authentifier le connecteur sur votre base de données KQL à l’aide d’un ID client. Les identités managées sont utilisées pour les applications qui s’exécutent dans Azure.

Authentification du principal de service Microsoft Entra
Authentification d’identité managée

Créer un principal de service Microsoft Entra

Créez un principal de service Microsoft Entra, puis autorisez ce principal comme identité utilisée par le connecteur pour ingérer des données dans votre base de données KQL.

Le principal du service Microsoft Entra peut être créé dans le portail Azure ou programmatiquement, comme dans l’exemple suivant.

Vous accorderez ultérieurement des autorisations pour ce principal de service afin d’accéder à des ressources Kusto

Connectez-vous à votre abonnement Azure via Azure CLI. Authentifiez-vous ensuite dans le navigateur.
```
az login
```
Choisissez l’abonnement pour héberger le principal. Cette étape est nécessaire quand vous avez plusieurs abonnements.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Créez le principal de service. Dans cet exemple, le principal de service est appelé my-service-principal.
```
az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}
```

À partir des données JSON retournées, copiez le appId, password et tenant pour une utilisation ultérieure.

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

Vous avez créé votre application Microsoft Entra et votre principal de service.

Créer une identité managée

Créez une identité managée et autorisez-la comme identité utilisée par le connecteur pour ingérer des données dans votre base de données KQL. Pour plus d’informations sur la création d’une identité managée, consultez Gérer les identités managées affectées par l’utilisateur.

Connectez-vous à votre abonnement Azure via Azure CLI. Authentifiez-vous ensuite dans le navigateur.
```
az login
```
Choisissez l’abonnement pour héberger l’identité managée. Cette étape est nécessaire quand vous avez plusieurs abonnements.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Créer une identité managée attribuée par l'utilisateur Dans cet exemple, l’identité managée est appelée my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Attribuez le rôle Contributeur pour l’étendue de l’abonnement à l’identité managée. Dans cet exemple, l’identité managée est appelée my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

À partir des données JSON retournées, copiez le clientId pour une utilisation future. Le format JSON est le suivant :

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

Vous avez créé votre identité gérée assignée par l'utilisateur.

Créer une table cible et un mappage d’ingestion

Créez une table cible pour les données entrantes et un mappage d’ingestion pour mapper les colonnes de données ingérées aux colonnes de la table cible. Dans les étapes suivantes, le schéma de table et le mappage correspondent aux données envoyées à partir de l’exemple d’application.

Exécutez la commande de création de table dans votre éditeur de requête, en remplaçant l’espace réservé TableName par le nom de la table cible :

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

Exécutez la commande de mappage d’ingestion .create suivante, en remplaçant les espaces réservés TableName par le nom de la table cible et TableNameMapping par le nom du mappage d’ingestion :

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

Accordez au principal de service Créer un principal de service Microsoft Entra les autorisations de rôle d’ingestion de base de données pour travailler avec la base de données. Pour plus d’informations, consultez Exemples. Remplacez l’espace réservé DatabaseName par le nom de la base de données cible et ApplicationID par la valeur AppId que vous avez enregistrée lors de la création d’un principal de service Microsoft Entra.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Utiliser Serilog dans votre application ASP.NET Core

Cette section explique comment intégrer Serilog dans votre application ASP.NET Core pour journaliser les données et les envoyer à votre table KQL.

Installer le package

Ajoutez le package de bibliothèque NuGet Serilog.Sinks.AzureDataExplorer. Utilisez la commande Install-Package en spécifiant le nom du package NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Ajouter le récepteur Serilog à votre application

Procédez comme suit pour :

Ajoutez le récepteur Serilog à votre application.
Configurez les variables utilisées par le récepteur.
Générez et exécutez l'application.

Ajoutez le code suivant à votre application :
```
using Serilog.Sinks.AzureDataExplorer;
```

Configurez le récepteur Serilog, en remplaçant les espaces réservés à l’aide des informations de la table suivantes :

Authentification du principal de service Microsoft Entra
Authentification d’identité managée

Pour l’authentification du principal de service Microsoft Entra, utilisez le code suivant :

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

Pour l’authentification d’identité managée, utilisez le code suivant :

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

Utilisez le tableau ci-dessous pour définir les valeurs des options d'évier :

Variable	Descriptif
`IngestionEndPointUri`	L’URI d’ingestion.
`DatabaseName`	Nom de la base de données cible, respectant la casse.
`TableName`	Le nom respectant la casse d’une table cible existante. Par exemple, SerilogTest est le nom de la table créée dans Créer une table cible et un mappage d’ingestion.
`AppId`	ID client d’application requis pour l’authentification du principal de service Microsoft Entra. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
`AppKey`	Clé d’application requise pour l’authentification du principal du service Microsoft Entra. Vous avez enregistré cette valeur sous `password` dans Créer un principal de service Microsoft Entra.
`Tenant`	ID du locataire dans lequel l’application est enregistrée lors de l’authentification par principal de service de Microsoft Entra. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
`BufferBaseFileName`	Nom de fichier de base facultatif pour le fichier de mémoire tampon. Définissez cette valeur si vous avez besoin que vos journaux soient durables par rapport à la perte de défaillances de connexion résultantes sur votre cluster. Par exemple : `C:/Temp/Serilog`.
`ManagedIdentityClientId`	ID client de l'identité gérée assignée par l'utilisateur, lors de l'utilisation de l'authentification par identité gérée.

Pour plus d’options, consultez Options du récepteur.

Envoyez des données à votre base de données à l’aide du récepteur Serilog. Par exemple :

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

Générez et exécutez l'application. Par exemple, si vous utilisez Visual Studio, appuyez sur F5.
Vérifiez que les données se trouvent dans votre table. Exécutez la requête suivante en remplaçant l’espace réservé par le nom de la table créée à l’étape précédente :
```
<TableName>
| take 10
```

Exécution de l'exemple d'application

Si vous n’avez pas vos propres données à tester, vous pouvez utiliser l’exemple d’application de générateur de journaux avec des exemples de données pour tester la configuration et l’utilisation du récepteur Serilog.

Clonez le référentiel Git du récepteur Serilog à l’aide de la commande Git suivante :
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

Définissez les variables environnementales suivantes pour configurer le récepteur Serilog :

Variable	Descriptif
`IngestionEndPointUri`	L’URI d’ingestion.
`DatabaseName`	Nom de la base de données cible, respectant la casse.
`TableName`	Le nom respectant la casse d’une table cible existante. Par exemple, SerilogTest est le nom de la table créée dans Créer une table cible et un mappage d’ingestion.
`AppId`	ID client d’application requis pour l’authentification du principal du service Microsoft Entra. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
`AppKey`	Clé d'application requise pour l'authentification du principal de service Microsoft Entra. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
`Tenant`	ID du locataire dans lequel l’application est enregistrée lors de l’authentification par principal de service de Microsoft Entra. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
`BufferBaseFileName`	Nom de fichier de base pour le fichier de mémoire tampon. Définissez cette valeur si vous avez besoin que vos journaux soient durables par rapport à la perte de défaillances de connexion résultantes sur votre cluster. Par exemple, `C:/Temp/Serilog`
`ManagedIdentityClientId`	ID client de l'identité gérée assignée par l'utilisateur, lors de l'utilisation de l'authentification par identité gérée.

Vous pouvez définir manuellement les variables d’environnement ou à l’aide des commandes suivantes :

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

Dans votre terminal, accédez au dossier racine du référentiel cloné et exécutez la commande .NET suivante pour générer l’application :
```
dotnet build src
```
Dans votre terminal, accédez au dossier des échantillons et exécutez la commande .NET suivante pour exécuter l’application :
```
dotnet build run
```

Dans l’environnement de requête, sélectionnez la base de données cible et exécutez la requête suivante pour explorer les données ingérées, en remplaçant l’espace réservé TableName par le nom de la table cible :
```
<TableName>
| take 10
```
Votre résultat devrait ressembler à l’image suivante :

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-06-09