Pozyskiwanie danych za pomocą ujścia serilogu do usługi Azure Data Explorer

  • Artykuł

Ważne

Ten łącznik może być używany w analizie w czasie rzeczywistym w usłudze Microsoft Fabric. Skorzystaj z instrukcji opisanych w tym artykule z następującymi wyjątkami:

Serilog to popularna platforma rejestrowania dla aplikacji .NET. Usługa Serilog umożliwia deweloperom kontrolowanie, które instrukcje dziennika są danymi wyjściowymi z dowolną szczegółowością na podstawie nazwy rejestratora, poziomu rejestratora i wzorca komunikatów. Ujście seriloga, znane również jako dodatek, dla usługi Azure Data Explorer przesyła strumieniowo dane dziennika do usługi Azure Data Explorer, gdzie można analizować i wizualizować dzienniki w czasie rzeczywistym.

Ten artykuł obejmuje następujące zagadnienia:

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

Wymagania wstępne

Konfigurowanie środowiska

W tej sekcji przygotujesz środowisko do użycia ujścia serilogu.

Instalowanie pakietu

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

Install-Package Serilog.Sinks.AzureDataExplorer

Tworzenie rejestracji aplikacji Microsoft Entra

Microsoft Entra uwierzytelnianie aplikacji jest używane w przypadku aplikacji, które muszą uzyskiwać dostęp do usługi Azure Data Explorer 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ę do pozyskiwania danych bazy danych usługi Azure Data Explorer.

  1. Korzystając z klastra usługi Azure Data Explorer, wykonaj kroki 1–7 w temacie Tworzenie rejestracji aplikacji Microsoft Entra w usłudze Azure Data Explorer.
  2. Zapisz następujące wartości do użycia w kolejnych krokach:
    • Identyfikator aplikacji (klienta)
    • Identyfikator katalogu (dzierżawcy)
    • Wartość klucza tajnego klienta

Udzielanie uprawnień aplikacji Microsoft Entra

  1. Na karcie zapytania internetowego interfejsu użytkownika połącz się z klastrem. Aby uzyskać więcej informacji na temat nawiązywania połączenia, zobacz Dodawanie klastrów.

  2. Przejdź do bazy danych, w której chcesz pozyskać dane.

  3. Uruchom następujące polecenie zarządzania, zastępując symbole zastępcze. Zastąp ciąg DatabaseName nazwą docelowej bazy danych i identyfikatorem ApplicationID wcześniej zapisaną wartością. To polecenie przyznaje aplikacji rolę ingestor bazy danych . Aby uzyskać więcej informacji, zobacz Zarządzanie rolami zabezpieczeń bazy danych.

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

    Uwaga

    Ostatni parametr to ciąg, który jest wyświetlany jako notatki podczas wykonywania zapytań dotyczących ról skojarzonych z bazą danych. Aby uzyskać więcej informacji, zobacz Wyświetlanie istniejących ról zabezpieczeń.

Tworzenie tabeli i mapowania pozyskiwania

Utwórz tabelę docelową dla danych przychodzących, mapując pozyskane kolumny danych na kolumny w tabeli docelowej. W poniższych krokach schemat tabeli i mapowanie odpowiadają danym wysyłanym z przykładowej aplikacji.

  1. W edytorze zapytań uruchom następujące polecenie tworzenia tabeli, 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 mapowania pozyskiwania, zastępując symbole zastępcze TableName nazwą tabeli docelowej i tabelą 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}]'

Dodawanie ujścia serilogu do aplikacji

Wykonaj następujące kroki, aby:

  • Dodawanie ujścia serilogu do aplikacji
  • Konfigurowanie zmiennych używanych 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 = "<cluster>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Zmienna Opis
    Identyfikator IngestionEndPointUri Identyfikator URI pozyskiwania klastra w klastrze> formatuhttps://ingest-<.<region.kusto.windows.net>.
    Databasename Uwzględniana wielkość liter nazwa docelowej bazy danych.
    TableName Rozróżniana wielkość liter w istniejącej tabeli docelowej. Na przykład SerilogTest jest nazwą tabeli utworzonej w sekcji Tworzenie tabeli i mapowania pozyskiwania.
    AppId Identyfikator klienta aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    Klucz aplikacji Klucz aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    Dzierżawa Identyfikator dzierżawy, w której zarejestrowano aplikację. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    BufferBaseFileName Opcjonalna nazwa pliku podstawowego dla pliku buforu. Ustaw tę wartość, jeśli dzienniki mają być trwałe przed utratą wynikową awarią połączenia z klastrem. Na przykład C:/Temp/Serilog.

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

  3. Wysyłanie danych do platformy Azure Data Explorer 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 klawisz F5.

  5. Sprawdź, czy dane są w klastrze. W internetowym interfejsie użytkownika uruchom następujące zapytanie, zastępując symbol zastępczy nazwą tabeli, która była używana wcześniej:

    <TableName>
| take 10

Uruchamianie przykładowej aplikacji

Użyj przykładowej aplikacji generatora dzienników jako przykładu pokazującego sposób konfigurowania i używania 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 klastra w klastrze> formatuhttps://ingest-<.<region.kusto.windows.net>.
    Databasename Uwzględniana wielkość liter nazwa docelowej bazy danych.
    TableName Rozróżniana wielkość liter w istniejącej tabeli docelowej. Na przykład SerilogTest jest nazwą tabeli utworzonej w sekcji Tworzenie tabeli i mapowania pozyskiwania.
    AppId Identyfikator klienta aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    Klucz aplikacji Klucz aplikacji wymagany do uwierzytelniania. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    Dzierżawa Identyfikator dzierżawy, w której zarejestrowano aplikację. Zapisano tę wartość w sekcji Tworzenie rejestracji aplikacji Microsoft Entra.
    BufferBaseFileName Nazwa pliku podstawowego dla pliku buforu. Ustaw tę wartość, jeśli dzienniki mają być trwałe przed utratą wynikową awarią 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

  5. W internetowym interfejsie użytkownika 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.

Zawartość pokrewna