Freigeben über

Erfassen von Daten mit dem Serilog in Azure Data Explorer

  • Artikel

Serilog ist ein beliebtes Protokollierungsframework für .NET-Anwendungen. Mit Serilog können Entwickler steuern, welche Protokollanweisungen ausgehend vom Namen der Protokollierung, der Protokollierungsebene und dem Nachrichtenmuster mit beliebiger Granularität ausgegeben werden sollen. Die Serilog-Senke, auch als Appender bezeichnet, streamt Ihre Protokolldaten an Ihre Tabelle, wo Sie Ihre Protokolle in Echtzeit analysieren und visualisieren können.

In diesem Artikel wird gezeigt, wie Sie Daten mit Serilog erfassen.

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

Voraussetzungen

Erstellen eines Microsoft Entra-Dienstprinzipals

Die Microsoft Entra-Anwendungsauthentifizierung wird für Anwendungen verwendet, die auf Ihre KQL Datenbanktabelle zugreifen müssen, ohne dass eine benutzende Person anwesend ist. Um Daten mithilfe des Serilog-Connectors zu erfassen, müssen Sie einen Microsoft Entra-Dienstprinzipal erstellen und registrieren und dann diesen Prinzipal als Identität autorisieren, die vom Connector zum Erfassen von Daten in Ihre KQL-Datenbank verwendet wird.

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

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.

Erstellen einer Zieltabelle und Erfassungszuordnung

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

  1. Führen Sie den folgenden Tabellenerstellungsbefehl im Abfrage-Editor 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 .create-Zuordnungsbefehl aus, und ersetzen Sie die Platzhalter TableName durch den Zieltabellennamen 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}]'

  3. Gewähren Sie dem Dienstprinzipal aus Microsoft Entra Dienstprinzipal erstellen Datenbankerfasser Rollenberechtigungen, um mit der Datenbank zu arbeiten. Weitere Informationen finden Sie unter Beispiele. Ersetzen Sie DatabaseName durch den Namen der Zieldatenbank und ApplicationID durch den AppId Wert, den Sie beim Erstellen eines Microsoft Entra-Dienstprinzipals gespeichert haben.

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

Verwenden von Serilog in Ihrer ASP.NET Core-Anwendung

In diesem Abschnitt wird erläutert, wie Sie Serilog in Ihre ASP.NET Core-Anwendung integrieren, um Daten zu protokollieren und an Ihre KQL-Tabelle zu senden.

Installieren des Pakets

Fügen Sie das Serilog.Sinks.AzureDataExplorer NuGet-Bibliothekspaket hinzu. Verwenden Sie den Befehl „Install-Package“, der den Namen des NuGet Pakets angibt.

Install-Package Serilog.Sinks.AzureDataExplorer

Hinzufügen der Serilog-Senke zu Ihrer App

Verwenden Sie die folgenden Schritte für Folgendes:

  • Fügen Sie der App die Serilog-Senke hinzu.
  • Konfigurieren Sie die variablen, die von der Senke verwendet werden.
  • Erstellen Sie die App, und führen Sie sie aus.

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

    using Serilog.Sinks.AzureDataExplorer;

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

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Variable Beschreibung
    IngestionEndPointUri Die Erfassungs-URI.
    DatabaseName Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung.
    TableName Der Name der vorhandenen Zieltabelle unter Berücksichtigung der Groß-/Kleinschreibung. Beispielsweise ist SerilogTest der Name der Tabelle, die in Erstellen einer Zieltablle und Erfassungszuordnung erstellt wurde.
    AppId Die für die Authentifizierung erforderliche Anwendungsclient-ID. Sie haben diesen Wert in Microsoft Entra Dienstprinzipal erstellen gespeichert.
    AppKey Der für die Authentifizierung erforderliche Anwendungsschlüssel. Sie haben diesen Wert als password unter Microsoft Entra Dienstprinzipal erstellen gespeichert.
    Mandant Die ID des Mandanten, in dem die Anwendung registriert ist. Sie haben diesen Wert in Microsoft Entra Dienstprinzipal erstellen gespeichert.
    BufferBaseFileName Optionaler Basisdateiname für die Pufferdatei. Legen Sie diesen Wert fest, wenn Ihre Protokolle dauerhaft sein müssen, um daraus resultierende Verbindungsfehler mit Ihrem Cluster zu vermeiden. Beispiel: C:/Temp/Serilog.

    Weitere Optionen finden Sie unter Senkenoptionen.

  3. Senden Sie Daten mithilfe der Serilog-Senke an Ihre Datenbank. Zum 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. Überprüfen Sie, ob sich die Daten in Ihrer Tabelle befinden. Führen Sie die folgende Abfrage aus, indem Sie den Platzhalter durch den Namen der Tabelle ersetzen, die in einem vorherigen Schritt erstellt wurde:

    <TableName>
| take 10

Ausführen der Beispiel-App

Wenn Sie keine eigenen Daten zum Testen haben, können Sie die Beispielprotokollgenerator-App mit Beispieldaten verwenden, um die Konfiguration und Verwendung der Serilog-Senke zu testen.

  1. Klonen Sie das git repo 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
    IngestionEndPointUri Die Erfassungs-URI.
    DatabaseName Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung.
    TableName Der Name der vorhandenen Zieltabelle unter Berücksichtigung der Groß-/Kleinschreibung. Beispielsweise ist SerilogTest der Name der Tabelle, die in Erstellen einer Zieltablle und Erfassungszuordnung erstellt wurde.
    AppId Client-ID der Anwendung, die für die Authentifizierung erforderlich ist. Sie haben diesen Wert in Microsoft Entra Dienstprinzipal erstellen gespeichert.
    AppKey Für die Authentifizierung erforderlicher Anwendungsschlüssel. Sie haben diesen Wert in Microsoft Entra Dienstprinzipal erstellen gespeichert.
    Mandant Die ID des Mandanten, in dem die Anwendung registriert ist. Sie haben diesen Wert in Microsoft Entra Dienstprinzipal erstellen gespeichert.
    BufferBaseFileName Der Basisdateiname für die Pufferdatei. Legen Sie diesen Wert fest, wenn Ihre Protokolle dauerhaft sein müssen, um daraus resultierende Verbindungsfehler mit Ihrem Cluster zu vermeiden. 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 Beispielordner, und führen Sie den folgenden .NET-Befehl aus, um die App auszuführen:

    dotnet build run

  1. Wählen Sie in der Abfrageumgebung die Zieldatenbank aus, und führen Sie die folgende Abfrage aus, um die erfassten Daten zu untersuchen, und ersetzen Sie den Platzhalter TableName durch den Namen der Zieltabelle:

    <TableName>
| take 10

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

    Screenshot der Tabelle mit 10 Funktionen und Ergebnissen.

Zugehöriger Inhalt