traceloggingprovider.h-Header

  • Artikel

TraceLogging ist ein System zum Protokollieren selbst beschreibender Ereignisse, die ohne Manifest decodiert werden können. Unter Windows wird TraceLogging verwendet, um Ereignisse der Ereignisablaufverfolgung für Windows (ETW) zu generieren.

Der TraceLoggingProvider.h-Header im Windows SDK verfügt über Makros und Inlinefunktionen zum Generieren von TraceLogging-codierten ETW-Ereignissen für Kernel- und Benutzermoduscode mithilfe von C oder C++.

Hinweis

TraceLoggingProvider.h erfordert konstante Werte zur Kompilierzeit für Ereignisattribute wie Anbietername, Ereignisname und Feldnamen. Um den Laufzeitaufwand zu minimieren, erstellt TraceLoggingProvider.h seine Datenstrukturen zur Kompilierzeit und speichert die Informationen im schreibgeschützten Arbeitsspeicher. Wenn Sie laufzeitdynamische Ereignisse generieren müssen, müssen Sie eine andere TraceLogging-Implementierung wie TraceLoggingDynamic verwenden.

Schnellstart

  • Verwenden Sie in einer C- oder CPP-Datei das Makro TRACELOGGING_DEFINE_PROVIDER , um ein globales Anbieterhandle zu deklarieren. Das Anbieterhandle stellt die Verbindung Ihrer Komponente mit ETW dar.
  • Verwenden Sie beim Komponentenstart (z. B. in main, wmain, DllMainoder DriverEntry) die Funktion TraceLoggingRegister , um die Verbindung Ihrer Komponente mit ETW zu öffnen.
  • Verwenden Sie beim Herunterfahren der Komponente die Funktion TraceLoggingUnregister , um die Verbindung Ihrer Komponente mit ETW zu schließen.
  • Verwenden Sie während der Komponentenausführung das Makro TraceLoggingWrite , um TraceLogging-codierte ETW-Ereignisse zu generieren.
  • Verwenden Sie bei Bedarf das Makro TRACELOGGING_DECLARE_PROVIDER in Headern, um das Anbieterhandle vorwärts zu deklarieren, damit es in anderen Teilen ihrer Komponente verwendet werden kann.
  • Verwenden Sie Tools wie WPR, Tracelog oder Traceview , um Ablaufverfolgungen zu sammeln.
  • Verwenden Sie Tools wie WPA, tracefmt oder traceview , um Ablaufverfolgungen zu decodieren und anzuzeigen.

Beispiel

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider, // Name of the provider handle
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Weitere Informationen finden Sie unter

traceloggingprovider.h enthält die folgenden Programmierschnittstellen:

Functions

 
TRACELOGGING_DECLARE_PROVIDER

Forward-deklariert ein Handle für einen TraceLogging-Anbieter.
TRACELOGGING_DEFINE_PROVIDER

Definiert ein Handle für einen TraceLogging-Anbieter.
TRACELOGGING_DEFINE_PROVIDER_STORAGE

Reserviert statischen Speicher für ein TraceLogging-Anbieterhandle, das vom Benutzer definiert wird. Bevorzugen Sie TRACELOGGING_DEFINE_PROVIDER diesem Makro.
TraceLoggingBinary

TraceLogging-Wrappermakro, das dem Ereignis ein Feld mit Binärdaten hinzufügt.
TraceLoggingChannel

TraceLogging-Wrappermakro, das den Kanal für das Ereignis festlegt.
TraceLoggingCustom

TraceLogging-Wrappermakro, das dem Ereignis ein Feld hinzufügt, das mithilfe eines benutzerdefinierten Serialisierungsprogramms gepackt wurde.
TraceLoggingCustomAttribute

TraceLogging-Wrappermakro, das dem PDB benutzerdefinierte Informationen zum Ereignis hinzufügt.
TraceLoggingDescription

TraceLogging-Wrappermakro, das die Beschreibung für das Ereignis festlegt.
TraceLoggingEventTag

TraceLogging-Wrappermakro, das das Ereignistag für das Ereignis festlegt.
TraceLoggingKeyword

TraceLogging-Wrappermakro, das die Schlüsselwort (keyword) für das Ereignis festlegt.
TraceLoggingLevel

TraceLogging-Wrappermakro, das die Ebene für das Ereignis festlegt
TraceLoggingOpcode

TraceLogging-Wrappermakro, das den Opcode für das Ereignis festlegt
TraceLoggingOptionGroup

TraceLogging-Makro zur Verwendung in TRACELOGGING_DEFINE_PROVIDER, um eine Anbietergruppe anzugeben.
TraceLoggingProviderEnabled

TraceLogging-Makro, um zu bestimmen, ob ein Ablaufverfolgungsconsumer auf ein Ereignis dieses Anbieters lauscht.
TraceLoggingProviderId

Ruft die Anbieter-ID eines TraceLogging-Anbieters ab.
TraceLoggingRegister

Registriert einen TraceLogging-Anbieter, damit er zum Protokollieren von Ereignissen verwendet werden kann.
TraceLoggingRegisterEx

Registriert einen TraceLogging-Anbieter, damit er zum Protokollieren von Ereignissen verwendet werden kann, wobei ein ETW-Aktivierungsrückruf angegeben wird.
TraceLoggingSetInformation

Konfiguriert einen TraceLogging-Anbieter durch Aufrufen von EventSetInformation.
TraceLoggingSocketAddress

TraceLogging-Wrappermakro, das dem Ereignis ein Feld mit einer Socketadresse hinzufügt.
TraceLoggingStruct

TraceLogging-Wrappermakro, das dem Ereignis ein Feld hinzufügt, das andere Felder enthält.
TraceLoggingUnregister

Hebt die Registrierung eines TraceLogging-Anbieters auf.
TraceLoggingValue

TraceLogging-Wrappermakro für C++, das dem Ereignis ein Feld mit einem automatisch abgeleiteten Typ hinzufügt.
TraceLoggingWrite

Gibt ein TraceLogging-Ereignis aus.
TraceLoggingWriteActivity

Gibt ein TraceLogging-Ereignis mit angegebenen Aktivitäts-IDs aus.