Udostępnij za pośrednictwem

Pozyskiwanie danych za pomocą ujścia usługi Serilog w usłudze Azure Data Explorer

  • Artykuł

Serilog to popularna platforma rejestrowania dla aplikacji .NET. Oprogramowanie Serilog umożliwia deweloperom kontrolowanie, które instrukcje dziennika są danymi wyjściowymi. Poziom szczegółowości może być ustalany dowolnie na podstawie nazwy rejestratora, poziomu rejestratora i wzorca komunikatów. Ujście serilog, znane również jako dodatek, przesyła strumieniowo dane dziennika do tabeli, gdzie można analizować i wizualizować dzienniki w czasie rzeczywistym.

W tym artykule pokazano, jak pozyskiwać dane za pomocą programu Serilog.

Aby uzyskać pełną listę łączników danych, zobacz Omówienie integracji danych.

Wymagania wstępne

  • Zestaw .NET SDK 6.0 lub nowszy
  • Klaster i baza danych usługi Azure Data Explorer z domyślną pamięcią podręczną i zasadami przechowywania.
  • Środowisko zapytań usługi Azure Data Explorer
  • Identyfikator URI klastra Kusto dla wartości TargetURI w klastrze> formatuhttps://ingest-<.<region.kusto.windows.net>. Aby uzyskać więcej informacji, zobacz Dodawanie połączenia klastra.

Tworzenie jednostki usługi Entra firmy Microsoft

Uwierzytelnianie aplikacji Entra firmy Microsoft jest używane w przypadku aplikacji, które muszą uzyskiwać dostęp do tabeli bazy danych KQL bez obecności użytkownika. Aby pozyskać dane przy użyciu łącznika Serilog, należy utworzyć i zarejestrować jednostkę usługi Microsoft Entra, a następnie autoryzować tę jednostkę jako tożsamość używaną przez łącznik do pozyskiwania danych do bazy danych KQL.

Jednostkę usługi Microsoft Entra można utworzyć za pośrednictwem witryny Azure Portal lub programowo, jak w poniższym przykładzie.

Później przyznasz uprawnienia dla tej jednostki usługi w celu uzyskania dostępu do zasobów usługi Kusto.

  1. Zaloguj się do subskrypcji platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure. Następnie uwierzytelnij się w przeglądarce.

    az login

  2. Wybierz subskrypcję do hostowania podmiotu zabezpieczeń. Ten krok jest wymagany, gdy masz wiele subskrypcji.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Utwórz jednostkę usługi. W tym przykładzie jednostka usługi nosi nazwę my-service-principal.

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

  4. Z zwróconych danych JSON skopiuj wartości appId, passwordi tenant do użycia w przyszłości.

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

Utworzono aplikację Microsoft Entra i jednostkę usługi.

Tworzenie tabeli docelowej i mapowania pozyskiwania

Utwórz tabelę docelową dla danych przychodzących i mapowanie pozyskiwania w celu zamapowania pozyskanych kolumn danych na kolumny w tabeli docelowej. W poniższych krokach schemat tabeli i mapowanie odpowiadają danym wysyłanym z przykładowej aplikacji.

  1. Uruchom następujące polecenie tworzenia tabeli w edytorze zapytań, zastępując symbol zastępczy TableName nazwą tabeli docelowej:

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

  2. Uruchom następujące polecenie .create ingestion mapping (Utwórz mapowanie pozyskiwania), zastępując symbole zastępcze TableName nazwą tabeli docelowej i parametrem TableNameMapping nazwą mapowania pozyskiwania:

    .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. Udziel jednostce usługi uprawnienia do pracy z bazą danych w bazie danych utwórz jednostkę usługi Microsoft Entra. Aby uzyskać więcej informacji, zobacz Przykłady. Zastąp symbol zastępczy DatabaseName nazwą docelowej bazy danych i identyfikatorem ApplicationID wartością AppId zapisaną podczas tworzenia jednostki usługi Microsoft Entra.

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

Używanie biblioteki Serilog w aplikacji ASP.NET Core

W tej sekcji wyjaśniono, jak zintegrować aplikację Serilog z aplikacją ASP.NET Core w celu rejestrowania danych i wysyłania ich do tabeli KQL.

Instalowanie pakietu

Dodaj pakiet biblioteki NuGet Serilog.Sinks.AzureDataExplorer. Użyj polecenia Install-Package, określając nazwę pakietu NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Dodawanie ujścia serilogu do aplikacji

Wykonaj następujące czynności, aby:

  • Dodaj ujście serilogu do aplikacji.
  • Skonfiguruj zmienne używane przez ujście.
  • Skompiluj i uruchom aplikację.

  1. Dodaj następujący kod do aplikacji:

    using Serilog.Sinks.AzureDataExplorer;

  2. Skonfiguruj ujście serilogu, zastępując symbole zastępcze przy użyciu informacji w poniższej tabeli:

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Zmienna opis
    Identyfikator IngestionEndPointUri Identyfikator URI pozyskiwania.
    Nazwa bazy danych W nazwie docelowej bazy danych uwzględniana jest wielkość liter.
    TableName W nazwie istniejącej tabeli docelowej jest uwzględniana wielkość liter. Na przykład SerilogTest jest nazwą tabeli utworzonej w sekcji Tworzenie tabeli docelowej i mapowania pozyskiwania.
    Identyfikator aplikacji Identyfikator klienta aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w temacie Create a Microsoft Entra service principal (Tworzenie jednostki usługi Firmy Microsoft Entra).
    Klucz aplikacji Klucz aplikacji wymagany do uwierzytelniania. Ta wartość jest zapisywana w sekcji password Tworzenie jednostki usługi Entra firmy Microsoft.
    Dzierżawca Identyfikator dzierżawy, w której zarejestrowano aplikację. Zapisano tę wartość w temacie Create a Microsoft Entra service principal (Tworzenie jednostki usługi Firmy Microsoft Entra).
    BufferBaseFileName Opcjonalna nazwa pliku podstawowego dla pliku buforu. Ustaw tę wartość, jeśli dzienniki mają być trwałe przed utratą wynikowymi niepowodzeniami połączenia z klastrem. Na przykład C:/Temp/Serilog.

    Aby uzyskać więcej opcji, zobacz Opcje ujścia.

  3. Wysyłanie danych do bazy danych przy użyciu ujścia serilogu. Na przykład:

    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. Skompiluj i uruchom aplikację. Jeśli na przykład używasz programu Visual Studio, naciśnij F5.

  5. Sprawdź, czy dane są w tabeli. Uruchom następujące zapytanie, zastępując symbol zastępczy nazwą tabeli utworzonej w poprzednim kroku:

    <TableName>
| take 10

Uruchamianie przykładowej aplikacji

Jeśli nie masz własnych danych do testowania, możesz użyć przykładowej aplikacji generatora dzienników z przykładowymi danymi, aby przetestować konfigurację i użyć ujścia serilogu.

  1. Sklonuj repozytorium git ujścia serilog przy użyciu następującego polecenia git:

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

  2. Ustaw następujące zmienne środowiskowe, aby skonfigurować ujście serilogu:

    Zmienna opis
    Identyfikator IngestionEndPointUri Identyfikator URI pozyskiwania.
    Nazwa bazy danych W nazwie docelowej bazy danych uwzględniana jest wielkość liter.
    TableName W nazwie istniejącej tabeli docelowej jest uwzględniana wielkość liter. Na przykład SerilogTest jest nazwą tabeli utworzonej w sekcji Tworzenie tabeli docelowej i mapowania pozyskiwania.
    Identyfikator aplikacji Identyfikator klienta aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w temacie Create a Microsoft Entra service principal (Tworzenie jednostki usługi Firmy Microsoft Entra).
    Klucz aplikacji Klucz aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w temacie Create a Microsoft Entra service principal (Tworzenie jednostki usługi Firmy Microsoft Entra).
    Dzierżawca Identyfikator dzierżawy, w której zarejestrowano aplikację. Zapisano tę wartość w temacie Create a Microsoft Entra service principal (Tworzenie jednostki usługi Firmy Microsoft Entra).
    BufferBaseFileName Nazwa pliku podstawowego dla pliku buforu. Ustaw tę wartość, jeśli dzienniki mają być trwałe przed utratą wynikowymi niepowodzeniami połączenia z klastrem. Na przykład C:/Temp/Serilog

    Zmienne środowiskowe można ustawić ręcznie lub za pomocą następujących poleceń:

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

  3. W terminalu przejdź do folderu głównego sklonowanego repozytorium i uruchom następujące polecenie platformy .NET, aby skompilować aplikację:

    dotnet build src

  4. W terminalu przejdź do folderu samples i uruchom następujące polecenie platformy .NET, aby uruchomić aplikację:

    dotnet build run

  1. W środowisku zapytań wybierz docelową bazę danych i uruchom następujące zapytanie, aby zbadać pozyskane dane, zastępując symbol zastępczy TableName nazwą tabeli docelowej:

    <TableName>
| take 10

    Dane wyjściowe powinny wyglądać podobnie do poniższej ilustracji:

    Zrzut ekranu przedstawiający tabelę z funkcją take 10 i wynikami.

Powiązana zawartość