Partager via

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

  • Article

Important

Ce connecteur peut être utilisé dans l’analyse en temps réel dans Microsoft Fabric. Utilisez les instructions de cet article avec les exceptions suivantes :

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 de l’enregistreur d’événements et du modèle de message de l’enregistreur d’événements. Le récepteur Serilog, également appelé appender, pour Azure Data Explorer diffuse vos données de journal vers Azure Data Explorer, où vous pouvez analyser et visualiser vos journaux en temps réel.

Dans cet article, vous allez apprendre à :

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

Prérequis

Configurer votre environnement

Dans cette section, vous allez préparer votre environnement à utiliser le récepteur Serilog.

Installer le package

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

Install-Package Serilog.Sinks.AzureDataExplorer

Créer une inscription d’application Microsoft Entra

Microsoft Entra’authentification d’application est utilisée pour les applications qui doivent accéder à Azure Data Explorer sans qu’un utilisateur soit présent. 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 à ingérer des données d’une base de données Azure Data Explorer.

  1. À l’aide de votre cluster Azure Data Explorer, suivez les étapes 1 à 7 dans Créer une inscription d’application Microsoft Entra dans Azure Data Explorer.
  2. Enregistrez les valeurs suivantes à utiliser dans les étapes suivantes :
    • ID d’application (client)
    • ID de l’annuaire (locataire)
    • Valeur de clé secrète client

Accorder les autorisations d’application Microsoft Entra

  1. Dans l’onglet requête de l’interface utilisateur web, connectez-vous à votre cluster. Pour plus d’informations sur la connexion, consultez Ajouter des clusters.

  2. Accédez à la base de données dans laquelle vous souhaitez ingérer des données.

  3. Exécutez la commande de gestion suivante, en remplaçant les espaces réservés. Remplacez DatabaseName par le nom de la base de données cible et ApplicationID par la valeur précédemment enregistrée. Cette commande accorde à l’application le rôle d’ingestion de base de données . Pour plus d’informations, consultez Gérer les rôles de sécurité de base de données.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'

    Notes

    Le dernier paramètre est une chaîne qui s’affiche sous la forme de notes lorsque vous interrogez les rôles associés à une base de données. Pour plus d’informations, consultez Afficher les rôles de sécurité existants.

Créer un mappage de table et d’ingestion

Créez une table cible pour les données entrantes, en mappant 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. Dans votre éditeur de requête, exécutez la commande de création de table suivante, 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 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}]'

Ajouter le récepteur Serilog à votre application

Procédez comme suit pour :

  • Ajouter le récepteur Serilog à votre application
  • Configurer les variables utilisées par le récepteur
  • Générer et exécuter 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 suivante :

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<cluster>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Variable Description
    IngestionEndPointUri URI d’ingestion de votre cluster au format https://ingest-<cluster>.<region.kusto.windows.net>.
    DatabaseName Nom de la base de données cible, respectant la casse.
    TableName 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 et un mappage d’ingestion.
    AppID ID client d’application requis pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    AppKey Clé d’application requise pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    Locataire ID du locataire dans lequel l’application est inscrite. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    BufferBaseFileName Nom de fichier de base facultatif pour le fichier tampon. Définissez cette valeur si vous avez besoin que vos journaux soient durables contre les échecs de connexion à votre cluster résultant d’une perte. Par exemple : C:/Temp/Serilog.

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

  3. Envoyez des données à Azure Data Explorer à 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 situent dans votre cluster. Dans l’interface utilisateur web, exécutez la requête suivante en remplaçant l’espace réservé par le nom de la table utilisée précédemment :

    <TableName>
| take 10

Exécution de l'exemple d'application

Utilisez l’exemple d’application générateur de journaux comme exemple montrant comment configurer et utiliser le 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 URI d’ingestion de votre cluster au format https://ingest-<cluster>.<region.kusto.windows.net>.
    DatabaseName Nom de la base de données cible, respectant la casse.
    TableName 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 et un mappage d’ingestion.
    AppID ID client d’application requis pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    AppKey Clé d’application requise pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    Locataire ID du locataire dans lequel l’application est inscrite. Vous avez enregistré cette valeur dans Créer une inscription d’application 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 contre les échecs de connexion à votre cluster résultant d’une perte. Par exemple : C:/Temp/Serilog

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

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

  3. Dans votre terminal, accédez au dossier racine du dépôt 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 samples et exécutez la commande .NET suivante pour exécuter l’application :

    dotnet build run

  5. Dans l’interface utilisateur web, 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 sortie doit ressembler à l’image suivante :

    Capture d’écran de la table avec la fonction take 10 et les résultats.

Contenu connexe