Partager via

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

  • Article

NLog est une plateforme de journalisation flexible et gratuite pour différentes plateformes .NET, notamment .NET standard. NLog vous permet d’écrire dans plusieurs cibles, telles qu’une base de données, un fichier ou une console. Avec NLog, vous pouvez modifier la configuration de journalisation à la volée. Le récepteur NLog est une cible pour NLog qui vous permet d’envoyer vos messages de journal à un cluster KQL. Le plug-in est basé sur la bibliothèque Azure-Kusto-Data et offre un moyen efficace de réceptionner vos journaux d’activité sur votre cluster.

Dans cet article, vous allez apprendre à ingérer des données avec le récepteur nLog.

Pour obtenir la liste complète des connecteurs de données, veuillez consulter la vue d’ensemble des connecteurs de données.

Prérequis

Paramétrer votre environnement

Dans cette section, vous allez préparer votre environnement pour utiliser le connecteur NLog.

Installer le package

Ajoutez le package NuGet NLog.Azure.Kusto. Utilisez la commande Install-Package en spécifiant le nom du package NuGet.

Install-Package NLog.Azure.Kusto

Créer une inscription d’application Microsoft Entra

L’authentification des applications Microsoft Entra est utilisée pour les applications qui doivent accéder à la plateforme sans la présence d’un utilisateur. Pour obtenir des données à l’aide du connecteur NLog, vous devez créer et enregistrer un principal de service Microsoft Entra, puis autoriser ce principal à obtenir des données à partir d’une base de données.

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

Ce principal de service sera l’identité utilisée par le connecteur pour écrire des données dans votre table dans Kusto. 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.

Enregistrez les valeurs suivantes pour les utiliser dans les étapes ultérieures : * ID d’application (client) * ID de répertoire (locataire) * valeur de la clé secrète du client

Accordez les autorisations d’application Microsoft Entra

  1. Dans votre environnement de requête, 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 en savoir plus, consultez Gérer les rôles de sécurité de bases de données.

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

    Remarque

    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, veuillez consulter Affichage des rôles de sécurité existants.

Créez une table et un mappage d’ingestion

Créez une table cible pour les données entrantes.

  • 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, FormattedMessage:dynamic, Exception:string, Properties:dynamic)

Ajout de la configuration cible à votre application

Procédez comme suit pour :

  • Ajout de la configuration cible
  • Générer et exécuter l’application

  1. Ajoutez la cible dans votre fichier de configuration NLog.

    <targets>
    <target name="targettable" xsi:type="TargetTable"
    IngestionEndpointUri="<Connection string>"
    Database="<Database name>"
    TableName="<Table name>"
    ApplicationClientId="<Entra App clientId>"
    ApplicationKey="<Entra App key>"
    Authority="<Entra tenant id>"
    />
</targets>

##Rules
<rules>
    <logger name="*" minlevel="Info" writeTo="adxtarget" />
</rules>

    Pour plus d’options, veuillez consulter le connecteur Nlog.

  2. Envoyez des données à l’aide du récepteur NLog. Par exemple :

    logger.Info("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
logger.Error(exceptionObj, "This was exception");
logger.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);
logger.Warn("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);

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

  4. Rassurez-vous que les données se situent dans votre cluster. Dans votre environnement de requête, exécutez la requête suivante en remplaçant l’espace réservé par le nom de la table que vous avez utilisée précédemment :

    <TableName>
| take 10

Exécution de l'exemple d'application

Utilisez l’application génératrice d’échantillons de journaux comme exemple pour montrer comment configurer et utiliser le récepteur NLog.

  1. Clonez le référentiel Git du récepteur NLog à l’aide de la commande Git suivante :

    git clone https://github.com/Azure/azure-kusto-nlog-sink.git

  2. Définissez les variables environnementales suivantes afin que le fichier de configuration NLog puisse les lire immédiatement à partir de l’environnement :

    Variable Description
    INGEST_ENDPOINT L’URI d’ingestion pour votre cible de données. Vous avez copié cet URI dans les prérequis.
    DATABASE Nom de la base de données cible, respectant la casse.
    APP_ID L’ID client d’application requis pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    APP_KEY La clé d’application requise pour l’authentification. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.
    AZURE_TENANT_ID L’identificateur du locataire où l’application est inscrite. Vous avez enregistré cette valeur dans Créer une inscription d’application Microsoft Entra.

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

    $env:INGEST_ENDPOINT="<ingestionURI>"
$env:APP_ID="<appId>"
$env:APP_KEY="<appKey>"
$env:AZURE_TENANT_ID="<tenant>"
$env:DATABASE="<databaseName>"

  3. Dans votre terminal, naviguez jusqu’au dossier racine du référentiel cloné et exécutez la commande dotnet suivante pour générer l’application :

    cd .\NLog.Azure.Kusto.Samples\
dotnet build

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

    dotnet run

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

    ADXNLogSample
| take 10

    Votre résultat devrait ressembler à l’image suivante :

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

Contenu connexe