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.

Créer un principal de service Microsoft Entra

L’authentification des applications Microsoft Entra est utilisée pour les applications qui doivent accéder à votre table de base de données KQL sans la présence d’un utilisateur. Pour ingérer des données à l’aide du connecteur Serilog, vous devez créer et inscrire un principal de service Microsoft Entra, puis autoriser 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

1. Connectez-vous à votre abonnement Azure via Azure CLI. Authentifiez-vous ensuite dans le navigateur.

   az login
   

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

3. 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}
   

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

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

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

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.

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

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

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

1. Ajoutez le code suivant à votre application :

   using Serilog.Sinks.AzureDataExplorer;
   

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

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

   Variable	Description
   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 de l’application requis pour l’authentification. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
   AppKey	La clé d’application requise pour l’authentification. Vous avez enregistré cette valeur sous password dans Créer un principal de service Microsoft Entra.
   Locataire	L’identificateur du locataire où l’application est inscrite. 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.

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

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

4. Générez et exécutez l'application. Par exemple, si vous utilisez Visual Studio, appuyez sur F5.

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

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

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

   Variable	Description
   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	L’ID client d’application requis pour l’authentification. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
   AppKey	La clé d’application requise pour l’authentification. Vous avez enregistré cette valeur dans Créer un principal de service Microsoft Entra.
   Locataire	L’identificateur du locataire où l’application est inscrite. 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

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

   Windows

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

   Mac/Linux

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

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

4. Dans votre terminal, accédez au dossier des échantillons et exécutez la commande .NET suivante pour exécuter l’application :

   dotnet build run
   

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

   

Contenu connexe

• Vue d’ensemble des intégrations de données
• Vue d’ensemble du Langage de requête Kusto (KQL)