Příjem dat pomocí jímky Serilog do Azure Data Exploreru

Serilog je oblíbené protokolovací rozhraní pro aplikace v .NET. Serilog umožňuje vývojářům řídit, které příkazy protokolu budou vypisovány s jakou úrovní podrobností, a to na základě názvu protokolovacího nástroje, jeho úrovně a vzoru zpráv. Jímka Serilog, označovaná také jako appender, streamuje data protokolu do tabulky, kde můžete analyzovat a vizualizovat protokoly v reálném čase.

Tento článek ukazuje, jak ingestovat data pomocí nástroje Serilog.

Úplný seznam datových konektorů najdete v přehledu integrace dat.

Požadavky

• .NET SDK 6.0 nebo novější
• Cluster a databáze Azure Data Exploreru s výchozími zásadami ukládání do mezipaměti a uchovávání informací.
• Dotazovací prostředí Azure Data Exploreru
• Identifikátor URI clusteru Kusto pro hodnotu TargetURI ve formátu https://ingest-<clusteru.><region.kusto.windows.net>. Další informace najdete v tématu Přidání připojení ke clusteru.

Vytvoření instančního objektu Microsoft Entra

Ověřování aplikací Microsoft Entra se používá pro aplikace, které potřebují přístup k tabulce databáze KQL bez přítomnosti uživatele. Pokud chcete ingestovat data pomocí konektoru Serilog, musíte vytvořit a zaregistrovat instanční objekt Microsoft Entra a pak tento objekt zabezpečení autorizovat jako identitu používanou konektorem k ingestování dat do databáze KQL.

Instanční objekt Microsoft Entra je možné vytvořit prostřednictvím webu Azure Portal nebo programově, jako v následujícím příkladu.

Později udělíte oprávnění pro tento instanční objekt pro přístup k prostředkům Kusto.

1. Přihlaste se ke svému předplatnému Azure prostřednictvím Azure CLI. Pak se ověřte v prohlížeči.

   az login
   

2. Zvolte předplatné, které má být hostitelem objektu zabezpečení. Tento krok je potřeba v případě, že máte více předplatných.

   az account set --subscription YOUR_SUBSCRIPTION_GUID
   

3. Vytvořte instanční objekt. V tomto příkladu se instanční objekt nazývá my-service-principal.

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

4. Z vrácených dat JSON zkopírujte appIdpasswordtenant a pro budoucí použití.

   {
     "appId": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
     "displayName": "my-service-principal",
     "name": "my-service-principal",
     "password": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn",
     "tenant": "1234abcd-e5f6-g7h8-i9j0-1234kl5678mn"
   }
   

Vytvořili jste aplikaci Microsoft Entra a instanční objekt.

Vytvoření cílové tabulky a mapování příjmu dat

Vytvořte cílovou tabulku pro příchozí data a mapování příjmu dat pro mapování přijatých sloupců dat na sloupce v cílové tabulce. V následujících krocích schéma tabulky a mapování odpovídají datům odesílaných z ukázkové aplikace.

1. Spuštěním následujícího příkazu pro vytvoření tabulky v editoru dotazů nahraďte zástupný název TableName názvem cílové tabulky:

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

2. Spusťte následující příkaz mapování příjmu dat .create a nahraďte zástupné symboly TableName názvem cílové tabulky a TableNameMapping názvem mapování příjmu dat:

   .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. Udělte instančnímu objektu z vytvoření oprávnění role Ingestor ingestor ingestor služby Microsoft Entra pro práci s databází. Další informace najdete v tématu Příklady. Zástupný název DatabaseName nahraďte názvem cílové databáze a ID aplikace AppId hodnotou, kterou jste uložili při vytváření instančního objektu Microsoft Entra.

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

Použití nástroje Serilog v aplikaci ASP.NET Core

Tato část vysvětluje, jak integrovat Serilog do aplikace ASP.NET Core pro protokolování dat a jejich odeslání do tabulky KQL.

Nainstalujte balíček .

Přidejte balíček knihovny NuGet Serilog.Sinks.AzureDataExplorer NuGet. Použijte příkaz Install-Package určující název balíčku NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Přidání jímky Serilog do aplikace

Pomocí následujících kroků:

• Přidejte jímku Serilog do aplikace.
• Nakonfigurujte proměnné používané jímkou.
• Sestavte a spusťte aplikaci.

1. Do aplikace přidejte následující kód:

   using Serilog.Sinks.AzureDataExplorer;
   

2. Nakonfigurujte jímku Serilog a nahraďte zástupné symboly pomocí informací v následující tabulce:

   var log = new LoggerConfiguration()
   .WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
   {
       IngestionEndpointUri = "<TargetURI>",
       DatabaseName = "<MyDatabase>",
       TableName = "<MyTable>",
       BufferBaseFileName = "<BufferBaseFileName>"
   })
   .CreateLogger();
   

   Proměnná	Popis
   Identifikátor IngestendPointUri	Identifikátor INGEST URI.
   Název databáze	V cílové databázi se rozlišují malá a velká písmena.
   TableName	Název existující cílové tabulky rozlišující malá a velká písmena. Například SerilogTest je název tabulky vytvořené v vytvoření cílové tabulky a mapování příjmu dat.
   AppId	ID klienta aplikace vyžadované pro ověřování. Tuto hodnotu jste uložili v části Vytvoření instančního objektu Microsoft Entra.
   AppKey	Klíč aplikace vyžadovaný k ověřování. Tuto hodnotu jste uložili jako password v části Vytvoření instančního objektu Microsoft Entra.
   Klient	ID tenanta, ve kterém je aplikace zaregistrovaná. Tuto hodnotu jste uložili v části Vytvoření instančního objektu Microsoft Entra.
   BufferBaseFileName	Volitelný název základního souboru pro soubor vyrovnávací paměti. Tuto hodnotu nastavte, pokud potřebujete, aby vaše protokoly byly odolné proti ztrátě výsledných selhání připojení ke clusteru. Například C:/Temp/Serilog.

   Další možnosti najdete v tématu Možnosti jímky.

3. Odešlete data do databáze pomocí jímky Serilog. Příklad:

   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. Sestavte a spusťte aplikaci. Pokud například používáte Visual Studio, stiskněte klávesu F5.

5. Ověřte, že jsou data v tabulce. Spuštěním následujícího dotazu nahraďte zástupný text názvem tabulky, kterou jste vytvořili v předchozím kroku:

   <TableName>
   | take 10
   

Spuštění ukázkové aplikace

Pokud nemáte k testování vlastní data, můžete použít ukázkovou aplikaci generátoru protokolů s ukázkovými daty k otestování konfigurace a použití jímky Serilog.

1. Naklonujte úložiště Git jímky Serilog pomocí následujícího příkazu Git:

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

2. Nastavte následující proměnné prostředí pro konfiguraci jímky Serilog:

   Proměnná	Popis
   Identifikátor IngestendPointUri	Identifikátor INGEST URI.
   Název databáze	V cílové databázi se rozlišují malá a velká písmena.
   TableName	Název existující cílové tabulky rozlišující malá a velká písmena. Například SerilogTest je název tabulky vytvořené v vytvoření cílové tabulky a mapování příjmu dat.
   AppId	ID klienta aplikace vyžadované pro ověřování. Tuto hodnotu jste uložili v části Vytvoření instančního objektu Microsoft Entra.
   AppKey	Klíč aplikace vyžadovaný pro ověřování. Tuto hodnotu jste uložili v části Vytvoření instančního objektu Microsoft Entra.
   Klient	ID tenanta, ve kterém je aplikace zaregistrovaná. Tuto hodnotu jste uložili v části Vytvoření instančního objektu Microsoft Entra.
   BufferBaseFileName	Název základního souboru pro soubor vyrovnávací paměti. Tuto hodnotu nastavte, pokud potřebujete, aby vaše protokoly byly odolné proti ztrátě výsledných selhání připojení ke clusteru. Například C:/Temp/Serilog

   Proměnné prostředí můžete nastavit ručně nebo pomocí následujících příkazů:

   Windows

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

   Mac/Linux

   export ingestionURI="<ingestionURI>"
   export appId="<appId>"
   export appKey="<appKey>"
   export tenant="<tenant>"
   export databaseName="<databaseName>"
   export tableName="<tableName>"
   

3. V terminálu přejděte do kořenové složky klonovaného úložiště a spuštěním následujícího příkazu .NET sestavte aplikaci:

   dotnet build src
   

4. V terminálu přejděte do složky s ukázkami a spuštěním následujícího příkazu .NET spusťte aplikaci:

   dotnet build run
   

3. V prostředí dotazu vyberte cílovou databázi a spuštěním následujícího dotazu prozkoumejte ingestovaná data a nahraďte zástupný název TableName názvem cílové tabulky:

   <TableName>
   | take 10
   

   Výstup by měl vypadat podobně jako na následujícím obrázku:

   

Související obsah

• Přehled integrace dat
• Přehled dotazovacího jazyka Kusto (KQL)