Freigeben über

Erfassen von Daten mit dem NLog in Azure Data Explorer

  • Artikel

NLog ist eine flexible und kostenlose Protokollierungsplattform für verschiedene .NET-Plattformen wie z.B. .NET-Standard. Mit NLog können Sie in mehrere Ziele schreiben, z.B. in eine Datenbank, Datei oder Konsole. Mit NLog können Sie die Protokollierungskonfiguration im laufenden Betrieb ändern. Die NLog-Senke ist ein Ziel für NLog, mit dem Sie Ihre Protokollmeldungen an einen KQL-Cluster senden können. Das Plugin baut auf der Bibliothek Azure-Kusto-Data auf und bietet eine effiziente Möglichkeit, Ihre Protokolle in Ihrem Cluster zu speichern.

In diesem Artikel erfahren Sie, wie Sie Daten mit einer NLog-Senke erfassen.

Eine vollständige Liste der Datenconnectors finden Sie in Übersicht der Datenconnectors.

Voraussetzungen

Erstellen Ihrer Umgebung

In diesem Abschnitt bereiten Sie Ihre Umgebung für die Verwendung des NLog-Connectors vor.

Installieren des Pakets

Fügen Sie das NuGet-Paket NLog.Azure.Kusto hinzu. Verwenden Sie den Befehl „Install-Package“, der den Namen des NuGet Pakets angibt.

Install-Package NLog.Azure.Kusto

Erstellen einer Microsoft Entra-App-Registrierung

Die Microsoft Entra-Anwendungsauthentifizierung wird für Anwendungen verwendet, die auf die Plattform zugreifen müssen, ohne dass eine benutzende Person anwesend ist. Um Daten mithilfe des NLog-Connectors abzurufen, müssen Sie einen Microsoft Entra-Dienstprinzipal erstellen und registrieren und dann diesen Prinzipal autorisieren, Daten aus einer Datenbank abzurufen.

Der Microsoft Entra-Dienstprinzipal kann über das Azure-Portal oder programmgesteuert (wie im folgenden Beispiel) erstellt werden.

Dieser Dienstprinzipal ist die Identität, die vom Connector zum Schreiben von Daten in die Ihre Tabelle in Kusto genutzt wird. Sie gewähren diesem Dienstprinzipal später noch Berechtigungen für den Zugriff auf Kusto-Ressourcen.

  1. Melden Sie sich per Azure CLI an Ihrem Azure-Abonnement an. Führen Sie anschließend im Browser die Authentifizierung durch.

    az login

  2. Wählen Sie das Abonnement aus, um den Prinzipal zu hosten. Dieser Schritt ist erforderlich, wenn Sie über mehrere Abonnements verfügen.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Erstellen Sie den Dienstprinzipal. In diesem Beispiel wird der Dienstprinzipal als my-service-principal bezeichnet.

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

  4. Kopieren Sie aus den zurückgegebenen JSON-Daten appId, password und tenant für die zukünftige Verwendung.

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

Sie haben Ihre Microsoft Entra-Anwendung und den Dienstprinzipal erstellt.

Speichern Sie die folgenden Werte, die in späteren Schritten verwendet werden sollen: *Anwendungs-ID (Client-ID) * Verzeichnis-ID (Mandanten-ID) * Wert des geheimen Clientschlüssels

Zuweisen der App-Berechtigung für Microsoft

  1. Führen Sie in Ihrer Abfrageumgebung den folgenden Verwaltungsbefehl aus, und ersetzen Sie die Platzhalter. Ersetzen Sie DatabaseName durch den Namen der Zieldatenbank und ApplicationID durch den zuvor gespeicherten Wert. Dieser Befehl gewährt der App die Rolle Datenbankingestor. Weitere Informationen finden Sie unter Verwalten von Sicherheitsrollen der Datenbank.

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

    Hinweis

    Der letzte Parameter ist eine Zeichenfolge, die als Notizen angezeigt wird, wenn Sie die einer Datenbank zugeordneten Rollen abfragen. Weitere Informationen finden Sie unter Vorhandene Sicherheitsrollen anzeigen.

Erstellen einer Tabellen- und Ingestionszuordnung

Erstellen Sie eine Zieltabelle für die eingehenden Daten.

  • Führen Sie im Abfrage-Editor den folgenden Tabellenerstellungsbefehl aus, und ersetzen Sie den Platzhalter TableName durch den Namen der Zieltabelle:

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

Hinzufügen der Zielkonfiguration zu Ihrer App

Verwenden Sie die folgenden Schritte für Folgendes:

  • Hinzufügen der Zielkonfiguration
  • Erstellen und Ausführen der App

  1. Fügen Sie das Ziel in der NLog-Konfigurationsdatei hinzu.

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

    Weitere Optionen finden Sie unter Nlog-Connector.

  2. Senden Sie Daten mithilfe der NLog-Senke. Zum Beispiel:

    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. Erstellen Sie die App, und führen Sie sie aus. Wenn Sie beispielsweise Visual Studio verwenden, drücken Sie F5.

  4. Überprüfen Sie, ob sich die Daten in Ihrem Cluster befinden. Führen Sie in Ihrer Abfrageumgebung die folgende Abfrage aus, indem Sie den Platzhalter durch den Namen der Tabelle ersetzen, die Sie zuvor verwendet haben:

    <TableName>
| take 10

Ausführen der Beispiel-App

Verwenden Sie die App zum Generieren von Beispielprotokollen als Beispiel, in dem gezeigt wird, wie die NLog-Senke konfiguriert und verwendet wird.

  1. Klonen Sie das git repo der NLog-Senke mit dem folgenden git-Befehl:

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

  2. Legen Sie die folgenden Umgebungsvariablen fest, sodass die NLog-Konfigurationsdatei sie direkt aus der Umgebung lesen kann:

    Variable Beschreibung
    INGEST_ENDPOINT Der Aufnahme-URI für Ihr Datenziel. Sie haben diesen URI unter Voraussetzungen kopiert.
    DATABASE Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung.
    APP_ID Client-ID der Anwendung, die für die Authentifizierung erforderlich ist. Sie haben diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung gespeichert.
    APP_KEY Für die Authentifizierung erforderlicher Anwendungsschlüssel. Sie speichern diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung.
    AZURE_TENANT_ID Die ID des Mandanten, in dem die Anwendung registriert ist. Sie speichern diesen Wert in Erstellen einer Microsoft Entra-App-Registrierung.

    Sie können die Umgebungsvariablen manuell oder mit den folgenden Befehlen festlegen:

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

  3. Navigieren Sie in Ihrem Terminal zum Stammordner des geklonten Repositorys, und führen Sie den folgenden dotnet-Befehl aus, um die App zu erstellen:

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

  4. Navigieren Sie in Ihrem Terminal zum Beispielordner, und führen Sie den folgenden dotnet-Befehl aus, um die App auszuführen:

    dotnet run

  5. Wählen Sie in Ihrer Abfrageumgebung die Zieldatenbank aus, und führen Sie die folgende Abfrage aus, um die aufgenommenen Daten zu untersuchen.

    ADXNLogSample
| take 10

    Ihre Ausgabe sollte in etwa wie in der folgenden Abbildung aussehen:

    Screenshot der Tabelle mit 10 Funktionen und Ergebnissen für „ÜBERNEHMEN“

Zugehöriger Inhalt