Share via

Erfassen von Daten mit der Serilog-Senke in Azure Data Explorer

  • Artikel

Wichtig

Dieser Connector kann in Echtzeitanalyse in Microsoft Fabric verwendet werden. Verwenden Sie die Anweisungen in diesem Artikel mit den folgenden Ausnahmen:

Serilog ist ein beliebtes Protokollierungsframework für .NET-Anwendungen. Mit Serilog können Entwickler steuern, welche Protokollanweisungen basierend auf dem Namen, der Protokollierungsebene und dem Nachrichtenmuster des Protokollierers mit beliebiger Granularität ausgegeben werden. Die Serilog-Senke, die auch als Anfügeprogramm bezeichnet wird, für Azure Data Explorer streamt Ihre Protokolldaten an Azure Data Explorer, wo Sie Ihre Protokolle in Echtzeit analysieren und visualisieren können.

In diesem Artikel lernen Sie Folgendes:

Eine vollständige Liste der Datenconnectors finden Sie unter Übersicht über Datenconnectors.

Voraussetzungen

Erstellen Ihrer Umgebung

In diesem Abschnitt bereiten Sie Ihre Umgebung auf die Verwendung der Serilog-Senke vor.

Installieren des Pakets

Fügen Sie das NuGet-Paket Serilog.Sinks.AzureDataExplorer hinzu. Verwenden Sie den Befehl Install-Package, um den Namen des NuGet-Pakets anzugeben.

Install-Package Serilog.Sinks.AzureDataExplorer

Erstellen einer Microsoft Entra App-Registrierung

Microsoft Entra Anwendungsauthentifizierung wird für Anwendungen verwendet, die auf Azure Data Explorer zugreifen müssen, ohne dass ein Benutzer anwesend ist. Zum Erfassen von Daten mithilfe des Serilog-Connectors müssen Sie einen Microsoft Entra Dienstprinzipal erstellen und registrieren und dann diesen Prinzipal autorisieren, Daten in einer Azure Data Explorer-Datenbank zu erfassen.

  1. Führen Sie mit Ihrem Azure Data Explorer-Cluster die Schritte 1 bis 7 unter Erstellen einer Microsoft Entra Anwendungsregistrierung in Azure Data Explorer aus.
  2. Speichern Sie die folgenden Werte, die in späteren Schritten verwendet werden sollen:
    • Anwendungs-ID (Client)
    • Verzeichnis-ID (Mandant)
    • Wert des geheimen Clientschlüssels

Erteilen von Berechtigungen für die Microsoft Entra-App

  1. Stellen Sie auf der Registerkarte Abfrage der Web-Benutzeroberfläche eine Verbindung mit Ihrem Cluster her. Weitere Informationen zum Herstellen einer Verbindung finden Sie unter Hinzufügen von Clustern.

  2. Navigieren Sie zu der Datenbank, in der Sie Daten erfassen möchten.

  3. Führen Sie den folgenden Verwaltungsbefehl aus, und ersetzen Sie die Platzhalter. Ersetzen Sie DatabaseName durch den Namen der Zieldatenbank und ApplicationID durch den zuvor gespeicherten Wert. Mit diesem Befehl wird der App die Datenbank-Ingestorrolle zugewiesen. Weitere Informationen finden Sie unter Verwalten von Datenbanksicherheitsrollen.

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

    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 Anzeigen vorhandener Sicherheitsrollen.

Erstellen einer Tabellen- und Erfassungszuordnung

Erstellen Sie eine Zieltabelle für die eingehenden Daten, und zuordnen Sie die erfassten Datenspalten den Spalten in der Zieltabelle. In den folgenden Schritten entsprechen das Tabellenschema und die Zuordnung den Daten, die von der Beispiel-App gesendet werden.

  1. Führen Sie im Abfrage-Editor den folgenden Befehl zur Tabellenerstellung aus, und ersetzen Sie den Platzhalter TableName durch den Namen der Zieltabelle:

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

  2. Führen Sie den folgenden Erfassungszuordnungsbefehl aus, und ersetzen Sie die Platzhalter TableName durch den Namen der Zieltabelle und TableNameMapping durch den Namen der Erfassungszuordnung:

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

Hinzufügen der Serilog-Senke zu Ihrer App

Führen Sie die folgenden Schritte aus:

  • Hinzufügen der Serilog-Senke zu Ihrer App
  • Konfigurieren der von der Senke verwendeten Variablen
  • Erstellen und Ausführen der App

  1. Fügen Sie Ihrer App den folgenden Code hinzu:

    using Serilog.Sinks.AzureDataExplorer;

  2. Konfigurieren Sie die Serilog-Senke, indem Sie Platzhalter mithilfe der folgenden Informationen in der Tabelle ersetzen:

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<cluster>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Variable BESCHREIBUNG
    ErfassungEndPointUri Der Erfassungs-URI für Ihren Cluster im Formatclusterhttps://ingest-<>.<region.kusto.windows.net>.
    DatabaseName Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung.
    TableName Der Name einer vorhandenen Zieltabelle, bei dem die Groß-/Kleinschreibung beachtet wird. SerilogTest ist beispielsweise der Name der Tabelle, die unter Erstellen einer Tabelle und Erfassungszuordnung erstellt wurde.
    AppId Die für die Authentifizierung erforderliche Anwendungsclient-ID. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    AppKey Der für die Authentifizierung erforderliche Anwendungsschlüssel. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    Mandant Die ID des Mandanten, in dem die Anwendung registriert ist. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    BufferBaseFileName Optionaler Basisdateiname für die Pufferdatei. Legen Sie diesen Wert fest, wenn Sie benötigen, dass Ihre Protokolle dauerhaft gegen Verlust bei Verbindungsfehlern mit Ihrem Cluster sind. Beispiel: C:/Temp/Serilog.

    Weitere Optionen finden Sie unter Senkenoptionen.

  3. Senden Sie Daten mithilfe der Serilog-Senke an Azure Data Explorer. Beispiel:

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

  5. Vergewissern Sie sich, dass sich die Daten in Ihrem Cluster befinden. Führen Sie auf der Webbenutzeroberfläche die folgende Abfrage aus, indem Sie den Platzhalter durch den Namen der zuvor verwendeten Tabelle ersetzen:

    <TableName>
| take 10

Ausführen der Beispiel-App

Verwenden Sie die Beispielprotokollgenerator-App als Beispiel für die Konfiguration und Verwendung der Serilog-Senke.

  1. Klonen Sie das Git-Repository der Serilog-Senke mit dem folgenden Git-Befehl:

    git clone https://github.com/Azure/serilog-sinks-azuredataexplorer

  2. Legen Sie die folgenden Umgebungsvariablen fest, um die Serilog-Senke zu konfigurieren:

    Variable BESCHREIBUNG
    ErfassungEndPointUri Der Erfassungs-URI für Ihren Cluster im Formatclusterhttps://ingest-<>.<region.kusto.windows.net>.
    DatabaseName Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung.
    TableName Der Name einer vorhandenen Zieltabelle, bei dem die Groß-/Kleinschreibung beachtet wird. SerilogTest ist beispielsweise der Name der Tabelle, die unter Erstellen einer Tabelle und Erfassungszuordnung erstellt wurde.
    AppId Anwendungsclient-ID erforderlich für die Authentifizierung. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    AppKey Für die Authentifizierung erforderlicher Anwendungsschlüssel. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    Mandant Die ID des Mandanten, in dem die Anwendung registriert ist. Sie haben diesen Wert unter Erstellen einer Microsoft Entra App-Registrierung gespeichert.
    BufferBaseFileName Der Basisdateiname für die Pufferdatei. Legen Sie diesen Wert fest, wenn Ihre Protokolle dauerhaft gegen verlustbedingte Verbindungsfehler mit Ihrem Cluster sein sollen. Zum Beispiel, C:/Temp/Serilog

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

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

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

    dotnet build src

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

    dotnet build run

  5. Wählen Sie auf der Webbenutzeroberfläche die Zieldatenbank aus, und führen Sie die folgende Abfrage aus, um die erfassten Daten zu untersuchen. Ersetzen Sie dabei den Platzhalter TableName durch den Namen der Zieltabelle:

    <TableName>
| take 10

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

    Screenshot der Tabelle mit 10er-Funktion und Ergebnissen.

Verwandte Inhalte