Sdílet prostřednictvím

Začínáme se službou EventSource

  • Článek

Tento článek se vztahuje na: ✔️ .NET Core 3.1 a novější verze ✔️ .NET Framework 4.5 a novější verze

Tento návod ukazuje, jak protokolovat novou událost pomocí System.Diagnostics.Tracing.EventSource, shromažďovat události v trasovacím souboru, zobrazit trasování a porozumět základním konceptům EventSource.

Poznámka

Mnoho technologií, které se integrují s EventSource, používá termíny 'Sledování' a 'Sledy' místo 'protokolování' a 'protokolů'. Význam je tady stejný.

Protokolování události

Cílem EventSource je umožnit vývojářům .NET psát kód, jako je tento, aby protokolovat událost:

DemoEventSource.Log.AppStarted("Hello World!", 12);

Tento řádek kódu obsahuje objekt protokolování (DemoEventSource.Log), metodu představující událost k protokolování (AppStarted) a volitelně některé parametry události silného typu (HelloWorld! a 12). Neexistují žádné úrovně podrobností, ID událostí, šablony zpráv ani nic jiného, co není potřeba v místě volání. Všechny tyto další informace o událostech jsou napsány definováním nové třídy odvozené z System.Diagnostics.Tracing.EventSource.

Tady je úplný minimální příklad:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
    }
}

DemoEventSource třída deklaruje metodu pro každý typ události, kterou chcete protokolovat. V tomto případě je jedna událost s názvem AppStarted definovaná metodou AppStarted(). Pokaždé, když kód vyvolá metodu AppStarted, do trasování se zaznamená jiná událost AppStarted, pokud je událost povolená. Toto jsou některá data, která se dají zachytit s každou událostí:

  • Název události – název, který identifikuje typ události, která byla zaznamenána. Název události bude stejný jako název metody AppStarted v tomto případě.
  • ID události – číselné ID, které identifikuje typ události, která byla zaznamenána. To slouží podobné roli jako název, ale může pomoct při rychlém automatizovaném zpracování protokolů. Událost AppStarted má ID 1 zadané v EventAttribute.
  • Název zdroje – název EventSource, který obsahuje událost. Slouží jako jmenný prostor pro události. Názvy a ID událostí musí být jedinečné jenom v rámci rozsahu jejich zdroje. Zde je zdroj pojmenován "Demo", zadaný v EventSourceAttribute definice třídy. Název zdroje se také běžně označuje jako název zprostředkovatele.
  • Argumenty – Všechny hodnoty argumentů metody jsou serializovány.
  • Další informace – Události můžou obsahovat také časové značky, ID vláken, ID procesoru, ID aktivit , výpisy zásobníku a metadata událostí, jako jsou šablony zpráv, úrovně podrobnosti a klíčová slova.

Další informace a osvědčené postupy pro vytváření událostí najdete v tématu Instrumentace kódu pro vytváření událostí.

Shromáždění a zobrazení trasovacího souboru

V kódu není požadovaná konfigurace, která popisuje, které události by se měly povolit, kam se mají protokolovaná data odesílat nebo ve kterém formátu by se data měla ukládat. Pokud teď aplikaci spustíte, ve výchozím nastavení nevygeneruje žádný trasovací soubor. EventSource používá vzor publikování a odběru , který vyžaduje, aby předplatitelé označili události, které by měly být povoleny, a řídili veškerou serializaci pro odebírané události. EventSource obsahuje integrace pro přihlášení k odběru z Trasování událostí pro Windows (ETW) a EventPipe (pouze .NET Core). Vlastní odběratele je možné vytvořit také pomocí rozhraní API System.Diagnostics.Tracing.EventListener.

Tato ukázka ukazuje EventPipe příklad pro aplikace .NET Core. Další informace najdete v tématu Shromažďování a zobrazování trasování událostí. EventPipe je otevřená a multiplatformní technologie trasování integrovaná do modulu runtime .NET Core, která vývojářům poskytuje nástroje pro shromažďování trasování .NET a přenositelný kompaktní formát trasování (soubory *.nettrace). dotnet-trace je nástroj příkazového řádku, který shromažďuje stopy EventPipe.

  1. Stáhněte a nainstalujte dotnet-trace.
  2. Sestavte výše uvedenou konzolovou aplikaci. Tato ukázka předpokládá, že aplikace má název EventSourceDemo.exe a nachází se v aktuálním adresáři. Na příkazovém řádku spusťte:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

Výstup by měl vypadat přibližně takto:

Provider Name                           Keywords            Level               Enabled By
Demo                                    0xFFFFFFFFFFFFFFFF  Verbose(5)          --providers

Launching: EventSourceDemo.exe
Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220303_001619.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

Tento příkaz spustil EventSourceDemo.exe se všemi událostmi ve 'Demo' EventSource a vytvořil výstupní trasovací soubor EventSourceDemo.exe_20220303_001619.nettrace. Otevření souboru v sadě Visual Studio zobrazuje události, které byly zaznamenány.

soubor nettrace sady Visual Studio

V zobrazení seznamu můžete vidět, že první událostí je událost Demo/AppStarted. Textový sloupec obsahuje uložené argumenty, sloupec časového razítka zobrazuje, že událost nastala 27 ms po zahájení protokolování, a napravo můžete vidět zásobník volání. Ostatní události jsou automaticky povoleny v každém sledování shromážděném pomocí dotnet-trace, i když je možné je ignorovat a filtrovat ze zobrazení v UI, pokud jsou unavující. Tyto dodatečné události zaznamenávají některé informace o procesu a jitovaném kódu, což Visual Studio umožňuje rekonstruovat trasování záznamů událostí.

Další informace o EventSource